/****************************************************************************

**

** 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