tests/auto/xmlpatternssdk/XMLWriter.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the test suite of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #ifndef PatternistSDK_XMLWriter_H
  43 #define PatternistSDK_XMLWriter_H
  44
  45 #include "Global.h"
  46
  47 #include <QtXml/QXmlContentHandler>
  48 #include <QtXml/QXmlLexicalHandler>
  49
  50 QT_BEGIN_HEADER
  51
  52 QT_BEGIN_NAMESPACE
  53
  54 class QIODevice;
  55
  56 namespace QPatternistSDK
  57 {
  58     /**
  59      * @short Serializes a stream of SAX events into XML, sent to a QIODevice.
  60      *
  61      * XMLWriter is a fast and simple XML serializer which takes care of
  62      * all the low level details of well-formedness and character escaping, allowing
  63      * the user to focus on higher level issues and increasing the chances of producing
  64      * valid, interoperable XML.
  65      *
  66      * The content XMLWriter produces is sent to a QIODevice, which is either
  67      * specified in XMLWriter's constructor or via setDevice(). If writing to
  68      * the device fails, the content functions such as startElement() returns @c false.
  69      *
  70      * XMLWriter sub-classes QXmlContentHandler meaning it can serialize content
  71      * from any code that produces SAX events. The class can also be used manually,
  72      * by calling startElement(), endCDATA(), and so forth.
  73      *
  74      * XMLWriter cannot be used to serialize multiple documents. One instance per
  75      * document must be used.
  76      *
  77      * XMLWriter takes care of escaping content into character references as necessary. Thus,
  78      * it should not be done manually. In fact, it would most likely
  79      * result in invalid XML or an unintended result. XMLWriter always serializes into UTF-8.
  80      *
  81      * When compiled in debug mode, XMLWriter contains several tests that helps
  82      * ensuring that XMLWriter produces valid XML. Some of these tests ensures that:
  83      *
  84      * - The @c xmlns and @c xml prefixes are used properly
  85      * - Content of comments and processing instructions is valid
  86      * - Element, attribute and DOCTYPE names are sensible
  87      * - Elements are properly nested and balanced
  88      * - To some extent that things occur in the proper order. For example, that
  89      *   the document type definition isn't added inside an element
  90      * - That namespaces prefixes are declared
  91      *
  92      * Not triggering XMLWriter's tests does not guarantee valid XML is produced,
  93      * but they do help catching common mistakes and some of the corner cases in the
  94      * specifications. When XMLWriter is compiled in release mode, these tests are not enabled
  95      * and the error handling in effect is concerning writing to the QIODevice.
  96      *
  97      * Often it is of interest to add a note at the beginning of the file communicating
  98      * it is auto-generated. setMessage() and setAddMessage() provides
  99      * a convenient way of doing that.
 100      *
 101      * Namespace declarations are added with startPrefixMapping(), not by sending attributes
 102      * with name <tt>xmlns:*</tt> to startElement().
 103      *
 104      * @see <a href="http://hsivonen.iki.fi/producing-xml/">HOWTO Avoid Being
 105      * Called a Bozo When Producing XML</a>
 106      * @see <a href="http://www.w3.org/TR/REC-xml/">Extensible Markup
 107      * Language (XML) 1.0 (Third Edition)</a>
 108      * @see <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML</a>
 109      * @todo Replace this class with QXmlStreamWriter
 110      * @author Frans Englich <frans.englich@nokia.com>
 111      * @ingroup PatternistSDK
 112      */
 113     class Q_PATTERNISTSDK_EXPORT XMLWriter : public QXmlContentHandler
 114                                            , public QXmlLexicalHandler
 115     {
 116     public:
 117         /**
 118          * Creates a XMLWriter which serializes its received events
 119          * to @p outStream.
 120          *
 121          * @note XMLWriter does not claim ownership of @p outStream. Thus,
 122          * @p outStream may not be destroyed as long as
 123          * this XMLWriter instance uses it.
 124          */
 125         XMLWriter(QIODevice *outStream = 0);
 126
 127         virtual ~XMLWriter();
 128
 129         /**
 130          * @returns @c true if opening the output device succeeds, otherwise @c false
 131          */
 132         virtual bool startDocument();
 133
 134         /**
 135          * @returns @c false if failure occurs in writing to the QIODevice, otherwise
 136          * @c true
 137          */
 138         virtual bool characters(const QString &ch);
 139
 140         /**
 141          * Starts an element with name @p qName and attributes @p atts. The prefix
 142          * in @p qName must first be declared with startPrefixMapping(), if it has one.
 143          *
 144          * A call to startElement() must always at some point be balanced with a call
 145          * to endElement().
 146          *
 147          * To declare namespaces, don't put attributes with name <tt>xmlns:*</tt> in @p atts,
 148          * but use startPrefixMapping().
 149          */
 150         virtual bool startElement(const QString &qName, const QXmlAttributes &atts = QXmlAttributes());
 151
 152         /**
 153          *
 154          * Behaves essentially as startElement(const QString &qName, const QXmlAttributes &atts). This
 155          * function is used in conjunction with other SAX classes.
 156          *
 157          * The call:
 158          *
 159          * @code
 160          * startElement(QString(), QString(), qName, atts);
 161          * @endcode
 162          *
 163          * is equivalent to:
 164          *
 165          * @code
 166          * startElement(qName, atts);
 167          * @endcode
 168          *
 169          * @p namespaceURI and @p localName are not used. This function is
 170          * used in conjunction with other SAX classes.
 171          *
 172          * @returns @c false if failure occurs in writing to the QIODevice, otherwise
 173          * @c true
 174          */
 175         virtual bool startElement(const QString &namespaceURI,
 176                                   const QString &localName,
 177                                   const QString &qName,
 178                                   const QXmlAttributes &atts);
 179
 180         /**
 181          * Signals the end of an element with name @p qName. @p qName must
 182          * be supplied.
 183          *
 184          * Calls to startElement() and endElement() must always be balanced.
 185          *
 186          * @returns @c false if failure occurs in writing to the QIODevice, otherwise
 187          * @c true
 188          */
 189         virtual bool endElement(const QString &qName);
 190
 191         /**
 192          * Behaves essentially as endElement(const QString &qName). This function
 193          * is used when XMLWriter is used in SAX code.
 194          *
 195          * @p namespaceURI and @p localName are not used.
 196          *
 197          * The call:
 198          *
 199          * @code
 200          * endElement(QString(), QString(), qName);
 201          * @endcode
 202          *
 203          * is equivalent to:
 204          *
 205          * @code
 206          * endElement(qName);
 207          * @endcode
 208          *
 209          * @returns @c false if failure occurs in writing to the QIODevice, otherwise
 210          * @c true
 211          */
 212         virtual bool endElement(const QString &namespaceURI,
 213                                 const QString &localName,
 214                                 const QString &qName);
 215
 216         /**
 217          * A description of an error if it occurred. This is typically
 218          * QIODevice::errorString(). If no error has occurred, an empty
 219          * string is returned.
 220          */
 221         virtual QString errorString() const;
 222
 223         /**
 224          * Starts a CDATA section. Content sent with characters() will not be escaped
 225          * except for ">" if occurring in "]]>".
 226          *
 227          * @returns @c false if failure occurs in writing to the QIODevice, otherwise
 228          * @c true
 229          */
 230         virtual bool startCDATA();
 231
 232         /**
 233          * @returns @c false if failure occurs in writing to the QIODevice, otherwise
 234          * @c true
 235          */
 236         virtual bool endCDATA();
 237
 238         /**
 239          * Creates a document type definition.
 240          *
 241          * For example, the code snippet:
 242          *
 243          * @code
 244          * writer.startDTD("html", "-//W3C//DTD XHTML 1.0 Strict//EN",
 245          *                 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd");
 246          * writer.endDTD();
 247          * @endcode
 248          *
 249          * would create:
 250          * @verbatim
 251  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 252 @endverbatim
 253          *
 254          * @note A system identifier must always be specified, but a public identifier may
 255          * be left out.
 256          *
 257          * A call to startDTD() must be followed by a call to endDTD().
 258          */
 259         virtual bool startDTD(const QString &name,
 260                               const QString &publicId,
 261                               const QString &systemId);
 262
 263         /**
 264          * Apart from closing the DTD, an new line is also added at end.
 265          */
 266         virtual bool endDTD();
 267
 268         /**
 269          * Creates a processing instruction by name @p target, and content
 270          * @p data.
 271          *
 272          * @returns @c false if failure occurs in writing to the QIODevice, otherwise
 273          * @c true
 274          */
 275         virtual bool processingInstruction(const QString &target,
 276                                            const QString &data);
 277
 278         /**
 279          * Declares a namespace which maps @p prefix to @p namespaceURI. For example, the call:
 280          *
 281          * @code
 282          * startPrefixMapping("xhtml", "http://www.w3.org/1999/xhtml");
 283          * @endcode
 284          *
 285          * would result in:
 286          *
 287          * @code
 288          * xmlns="http://www.w3.org/1999/xhtml"
 289          * @endcode
 290          */
 291         virtual bool startPrefixMapping(const QString &prefix,
 292                                         const QString &namespaceURI);
 293
 294         /**
 295          * Creates a comment with content @p ch. @p ch is escaped, there's
 296          * no need to do it manually. For example, calling comment() with @p ch
 297          * set to "my comment", results in "<!--my comment-->" in the output.
 298          *
 299          * @note if @p ch contains double hyphen("--"), the produced XML will
 300          * not be well formed.
 301          *
 302          * @returns @c false if failure occurs in writing to the QIODevice, otherwise
 303          * @c true
 304          */
 305         virtual bool comment(const QString &ch);
 306
 307         virtual bool startEntity(const QString &name);
 308         virtual bool endEntity(const QString &name);
 309
 310         /**
 311          * Sets the message which is added as a comment if addModificationMessage()
 312          * is set to @c true. If no message is specified and addModificationMessage()
 313          * is set to @c true, a default message is used.
 314          *
 315          * @see modificationMessage(), setAddMessage()
 316          */
 317         virtual void setMessage(const QString &msg);
 318
 319         /**
 320          * The message that is added at the beginning of the XML events
 321          * in a comment node. If no modificationMessage is set via modificationMessage(),
 322          * and addModificationMessage is set to @c true, this message will be used:
 323          * "NOTE: This file was automatically generated by [the application name] at
 324          * [the current date time]. All changes to this file will be lost."
 325          *
 326          * @see setMessage()
 327          */
 328         virtual QString modificationMessage() const;
 329
 330         /**
 331          * Closes the QIODevice XMLWriter writes to.
 332          */
 333         virtual bool endDocument();
 334
 335         /**
 336          * Serializes @p ch as if it was sent to characters().
 337          *
 338          * @returns @c false if failure occurs in writing to the QIODevice, otherwise
 339          * @c true
 340          */
 341         virtual bool ignorableWhitespace(const QString &ch);
 342
 343         /**
 344          * This function is not used by XMLWriter, but is implemented
 345          * in order to satisfy QXmlContentHandler's interface.
 346          */
 347         virtual bool endPrefixMapping(const QString &prefix);
 348
 349         /**
 350          * This function is not used by XMLWriter, but is implemented
 351          * in order to satisfy QXmlContentHandler's interface.
 352          */
 353         virtual bool skippedEntity(const QString &name);
 354
 355         /**
 356          * This function is not used by XMLWriter, but is implemented
 357          * in order to satisfy QXmlContentHandler's interface.
 358          */
 359         virtual void setDocumentLocator(QXmlLocator *);
 360
 361         /**
 362          * @returns the device XMLWriter writes its output to.
 363          * XMLWriter does not own the device.
 364          */
 365         virtual QIODevice *device() const;
 366
 367         /**
 368          * Sets the QIODevice XMLWriter writes to, to @p device. A device must be specified
 369          * either via this function or in the constructor before XMLWriter is used.
 370          *
 371          * XMLWriter does not claim ownership of @p device.
 372          */
 373         virtual void setDevice(QIODevice *device);
 374
 375         /**
 376          * Determines whether the modification message should be inserted as a comment
 377          * before the document element. The message returned by modificationMessage() is used.
 378          *
 379          * If @p toggle is @c true, the message will be added, otherwise not.
 380          */
 381         virtual void setAddMessage(const bool toggle);
 382
 383         /**
 384          * Tells whether a modification message will be added.
 385          *
 386          * @see setAddMessage(), modificationMessage()
 387          */
 388         virtual bool addModificationMessage() const;
 389
 390     private:
 391         Q_DISABLE_COPY(XMLWriter)
 392
 393         class Private;
 394         Private *d;
 395     };
 396 }
 397
 398 QT_END_NAMESPACE
 399
 400 QT_END_HEADER
 401
 402 #endif
 403 // vim: et:ts=4:sw=4:sts=4