summaryrefslogtreecommitdiffstats
path: root/tests/auto/xmlpatternssdk/XMLWriter.h
blob: 2b629bb179547167b7fee1e06128eec6321b329a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the test suite of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights.  These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

#ifndef PatternistSDK_XMLWriter_H
#define PatternistSDK_XMLWriter_H

#include "Global.h"

#include <QtXml/QXmlContentHandler>
#include <QtXml/QXmlLexicalHandler>

QT_BEGIN_HEADER

QT_BEGIN_NAMESPACE

class QIODevice;

namespace QPatternistSDK
{
    /**
     * @short Serializes a stream of SAX events into XML, sent to a QIODevice.
     *
     * XMLWriter 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 XMLWriter produces is sent to a QIODevice, which is either
     * specified in XMLWriter's constructor or via setDevice(). If writing to
     * the device fails, the content functions such as startElement() returns @c false.
     *
     * XMLWriter sub-classes QXmlContentHandler 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.
     *
     * XMLWriter cannot be used to serialize multiple documents. One instance per
     * document must be used.
     *
     * XMLWriter 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. XMLWriter always serializes into UTF-8.
     *
     * When compiled in debug mode, XMLWriter contains several tests that helps
     * ensuring that XMLWriter produces valid XML. Some of these tests ensures that:
     *
     * - The @c xmlns and @c 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 XMLWriter'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 XMLWriter is compiled in release mode, these tests are not enabled
     * and the error handling in effect is concerning writing to the QIODevice.
     *
     * Often it is of interest to add a note at the beginning of the file communicating
     * it is auto-generated. setMessage() and setAddMessage() provides
     * a convenient way of doing that.
     *
     * Namespace declarations are added with startPrefixMapping(), not by sending attributes
     * with name <tt>xmlns:*</tt> to startElement().
     *
     * @see <a href="http://hsivonen.iki.fi/producing-xml/">HOWTO Avoid Being
     * Called a Bozo When Producing XML</a>
     * @see <a href="http://www.w3.org/TR/REC-xml/">Extensible Markup
     * Language (XML) 1.0 (Third Edition)</a>
     * @see <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML</a>
     * @todo Replace this class with QXmlStreamWriter
     * @author Frans Englich <frans.englich@nokia.com>
     * @ingroup PatternistSDK
     */
    class Q_PATTERNISTSDK_EXPORT XMLWriter : public QXmlContentHandler
                                           , public QXmlLexicalHandler
    {
    public:
        /**
         * Creates a XMLWriter which serializes its received events
         * to @p outStream.
         *
         * @note XMLWriter does not claim ownership of @p outStream. Thus,
         * @p outStream may not be destroyed as long as
         * this XMLWriter instance uses it.
         */
        XMLWriter(QIODevice *outStream = 0);

        virtual ~XMLWriter();

        /**
         * @returns @c true if opening the output device succeeds, otherwise @c false
         */
        virtual bool startDocument();

        /**
         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
         * @c true
         */
        virtual bool characters(const QString &ch);

        /**
         * Starts an element with name @p qName and attributes @p atts. The prefix
         * in @p 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 <tt>xmlns:*</tt> in @p atts,
         * but use startPrefixMapping().
         */
        virtual bool startElement(const QString &qName, const QXmlAttributes &atts = QXmlAttributes());

        /**
         *
         * Behaves essentially as startElement(const QString &qName, const QXmlAttributes &atts). This
         * function is used in conjunction with other SAX classes.
         *
         * The call:
         *
         * @code
         * startElement(QString(), QString(), qName, atts);
         * @endcode
         *
         * is equivalent to:
         *
         * @code
         * startElement(qName, atts);
         * @endcode
         *
         * @p namespaceURI and @p localName are not used. This function is
         * used in conjunction with other SAX classes.
         *
         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
         * @c true
         */
        virtual bool startElement(const QString &namespaceURI,
                                  const QString &localName,
                                  const QString &qName,
                                  const QXmlAttributes &atts);

        /**
         * Signals the end of an element with name @p qName. @p qName must
         * be supplied.
         *
         * Calls to startElement() and endElement() must always be balanced.
         *
         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
         * @c true
         */
        virtual bool endElement(const QString &qName);

        /**
         * Behaves essentially as endElement(const QString &qName). This function
         * is used when XMLWriter is used in SAX code.
         *
         * @p namespaceURI and @p localName are not used.
         *
         * The call:
         *
         * @code
         * endElement(QString(), QString(), qName);
         * @endcode
         *
         * is equivalent to:
         *
         * @code
         * endElement(qName);
         * @endcode
         *
         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
         * @c true
         */
        virtual bool endElement(const QString &namespaceURI,
                                const QString &localName,
                                const QString &qName);

        /**
         * A description of an error if it occurred. This is typically
         * QIODevice::errorString(). If no error has occurred, an empty
         * string is returned.
         */
        virtual QString errorString() const;

        /**
         * Starts a CDATA section. Content sent with characters() will not be escaped
         * except for ">" if occurring in "]]>".
         *
         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
         * @c true
         */
        virtual bool startCDATA();

        /**
         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
         * @c true
         */
        virtual bool endCDATA();

        /**
         * Creates a document type definition.
         *
         * For example, the code snippet:
         *
         * @code
         * writer.startDTD("html", "-//W3C//DTD XHTML 1.0 Strict//EN",
         *                 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd");
         * writer.endDTD();
         * @endcode
         *
         * would create:
         * @verbatim
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
@endverbatim
         *
         * @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().
         */
        virtual bool startDTD(const QString &name,
                              const QString &publicId,
                              const QString &systemId);

        /**
         * Apart from closing the DTD, an new line is also added at end.
         */
        virtual bool endDTD();

        /**
         * Creates a processing instruction by name @p target, and content
         * @p data.
         *
         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
         * @c true
         */
        virtual bool processingInstruction(const QString &target,
                                           const QString &data);

        /**
         * Declares a namespace which maps @p prefix to @p namespaceURI. For example, the call:
         *
         * @code
         * startPrefixMapping("xhtml", "http://www.w3.org/1999/xhtml");
         * @endcode
         *
         * would result in:
         *
         * @code
         * xmlns="http://www.w3.org/1999/xhtml"
         * @endcode
         */
        virtual bool startPrefixMapping(const QString &prefix,
                                        const QString &namespaceURI);

        /**
         * Creates a comment with content @p ch. @p ch is escaped, there's
         * no need to do it manually. For example, calling comment() with @p ch
         * set to "my comment", results in "<!--my comment-->" in the output.
         *
         * @note if @p ch contains double hyphen("--"), the produced XML will
         * not be well formed.
         *
         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
         * @c true
         */
        virtual bool comment(const QString &ch);

        virtual bool startEntity(const QString &name);
        virtual bool endEntity(const QString &name);

        /**
         * Sets the message which is added as a comment if addModificationMessage()
         * is set to @c true. If no message is specified and addModificationMessage()
         * is set to @c true, a default message is used.
         *
         * @see modificationMessage(), setAddMessage()
         */
        virtual void setMessage(const QString &msg);

        /**
         * The message that is added at the beginning of the XML events
         * in a comment node. If no modificationMessage is set via modificationMessage(),
         * and addModificationMessage is set to @c true, this message will be used:
         * "NOTE: This file was automatically generated by [the application name] at
         * [the current date time]. All changes to this file will be lost."
         *
         * @see setMessage()
         */
        virtual QString modificationMessage() const;

        /**
         * Closes the QIODevice XMLWriter writes to.
         */
        virtual bool endDocument();

        /**
         * Serializes @p ch as if it was sent to characters().
         *
         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
         * @c true
         */
        virtual bool ignorableWhitespace(const QString &ch);

        /**
         * This function is not used by XMLWriter, but is implemented
         * in order to satisfy QXmlContentHandler's interface.
         */
        virtual bool endPrefixMapping(const QString &prefix);

        /**
         * This function is not used by XMLWriter, but is implemented
         * in order to satisfy QXmlContentHandler's interface.
         */
        virtual bool skippedEntity(const QString &name);

        /**
         * This function is not used by XMLWriter, but is implemented
         * in order to satisfy QXmlContentHandler's interface.
         */
        virtual void setDocumentLocator(QXmlLocator *);

        /**
         * @returns the device XMLWriter writes its output to.
         * XMLWriter does not own the device.
         */
        virtual QIODevice *device() const;

        /**
         * Sets the QIODevice XMLWriter writes to, to @p device. A device must be specified
         * either via this function or in the constructor before XMLWriter is used.
         *
         * XMLWriter does not claim ownership of @p device.
         */
        virtual void setDevice(QIODevice *device);

        /**
         * Determines whether the modification message should be inserted as a comment
         * before the document element. The message returned by modificationMessage() is used.
         *
         * If @p toggle is @c true, the message will be added, otherwise not.
         */
        virtual void setAddMessage(const bool toggle);

        /**
         * Tells whether a modification message will be added.
         *
         * @see setAddMessage(), modificationMessage()
         */
        virtual bool addModificationMessage() const;

    private:
        Q_DISABLE_COPY(XMLWriter)

        class Private;
        Private *d;
    };
}

QT_END_NAMESPACE

QT_END_HEADER

#endif
// vim: et:ts=4:sw=4:sts=4