src/xmlpatterns/data/qsequencereceiver_p.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Lesser General Public License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Lesser
  19 ** General Public License version 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Digia gives you certain additional
  26 ** rights.  These rights are described in the Digia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** GNU General Public License Usage
  30 ** Alternatively, this file may be used under the terms of the GNU
  31 ** General Public License version 3.0 as published by the Free Software
  32 ** Foundation and appearing in the file LICENSE.GPL included in the
  33 ** packaging of this file.  Please review the following information to
  34 ** ensure the GNU General Public License version 3.0 requirements will be
  35 ** met: http://www.gnu.org/copyleft/gpl.html.
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 //
  43 //  W A R N I N G
  44 //  -------------
  45 //
  46 // This file is not part of the Qt API.  It exists purely as an
  47 // implementation detail.  This header file may change from version to
  48 // version without notice, or even be removed.
  49 //
  50 // We mean it.
  51
  52 #ifndef Patternist_SequenceReceiver_H
  53 #define Patternist_SequenceReceiver_H
  54
  55 #include <QSharedData>
  56
  57 #include <private/qitem_p.h>
  58
  59 QT_BEGIN_HEADER
  60
  61 QT_BEGIN_NAMESPACE
  62
  63 namespace QPatternist
  64 {
  65     /**
  66      * @short A push interface for the XPath Data Model. Similar to SAX's
  67      * ContentHandler.
  68      *
  69      * @ingroup Patternist_xdm
  70      * @author Frans Englich <frans.englich@nokia.com>
  71      */
  72     class QAbstractXmlReceiver : public QSharedData
  73     {
  74     public:
  75         typedef QExplicitlySharedDataPointer<QAbstractXmlReceiver> Ptr;
  76
  77         inline QAbstractXmlReceiver()
  78         {
  79         }
  80
  81         virtual ~QAbstractXmlReceiver();
  82
  83         /**
  84          * @short Signals the start of an element by name @p name.
  85          */
  86         virtual void startElement(const QXmlName name) = 0;
  87
  88         /**
  89          * @short Signals the presence of the namespace declaration @p nb.
  90          *
  91          * This event is received @c after startElement(), as opposed to
  92          * SAX, and before any attribute() events.
  93          */
  94         virtual void namespaceBinding(const QXmlName &nb) = 0;
  95
  96         /**
  97          * @short Signals the end of the current element.
  98          */
  99         virtual void endElement() = 0;
 100
 101         /**
 102          * @short Signals the presence of an attribute node.
 103          *
 104          * This function is guaranteed by the caller to always be
 105          * called after a call to startElement() or attribute().
 106          *
 107          * @param name the name of the attribute. Guaranteed to always be
 108          * non-null.
 109          * @param value the value of the attribute. Guaranteed to always be
 110          * non-null.
 111          */
 112         virtual void attribute(const QXmlName name,
 113                                const QString &value) = 0;
 114
 115         virtual void processingInstruction(const QXmlName name,
 116                                            const QString &value) = 0;
 117         virtual void comment(const QString &value) = 0;
 118
 119         /**
 120          * @short Sends an Item to this QAbstractXmlReceiver that may be a QXmlNodeModelIndex or an
 121          * AtomicValue.
 122          */
 123         virtual void item(const Item &item) = 0;
 124
 125         /**
 126          * Sends a text node with value @p value. Adjascent text nodes
 127          * may be sent. There's no restrictions on @p value, beyond that it
 128          * must be valid XML characters. For instance, @p value may contain
 129          * only whitespace.
 130          *
 131          * @see whitespaceOnly()
 132          */
 133         virtual void characters(const QString &value) = 0;
 134
 135         /**
 136          * This function may be called instead of characters() if, and only if,
 137          * @p value consists only of whitespace.
 138          *
 139          * The caller gurantees that @p value, is not empty.
 140          *
 141          * By whitespace is meant a sequence of characters that are either
 142          * spaces, tabs, or the two new line characters, in any order. In
 143          * other words, the whole of Unicode's whitespace category is not
 144          * considered whitespace.
 145          *
 146          * However, there's no guarantee or requirement that whitespaceOnly()
 147          * is called for text nodes containing whitespace only, characters()
 148          * may be called just as well. This is why the default implementation
 149          * for whitespaceOnly() calls characters().
 150          *
 151          * @see characters()
 152          */
 153         virtual void whitespaceOnly(const QStringRef &value);
 154
 155         /**
 156          * Start of a document node.
 157          */
 158         virtual void startDocument() = 0;
 159
 160         /**
 161          * End of a document node.
 162          */
 163         virtual void endDocument() = 0;
 164
 165     protected:
 166         /**
 167          * Treats @p outputItem as an node and calls the appropriate function,
 168          * such as attribute() or comment(), depending on its QXmlNodeModelIndex::NodeKind.
 169          *
 170          * This a helper function sub-classes can use to multi-plex Nodes received
 171          * via item().
 172          *
 173          * @param outputItem must be a QXmlNodeModelIndex.
 174          */
 175         void sendAsNode(const Item &outputItem);
 176
 177     private:
 178         /**
 179          * Call sendAsNode() for each child of @p node. As consistent with the
 180          * XPath Data Model, this does not include attribute nodes.
 181          */
 182         template<const QXmlNodeModelIndex::Axis axis>
 183         inline void sendFromAxis(const QXmlNodeModelIndex &node);
 184         Q_DISABLE_COPY(QAbstractXmlReceiver)
 185     };
 186 }
 187
 188 QT_END_NAMESPACE
 189
 190 QT_END_HEADER
 191
 192 #endif