src/xmlpatterns/api/qabstractxmlpullprovider.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2008 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** GNU Lesser General Public License Usage
  11 ** This file may be used under the terms of the GNU Lesser General Public
  12 ** License version 2.1 as published by the Free Software Foundation and
  13 ** appearing in the file LICENSE.LGPL included in the packaging of this
  14 ** file. Please review the following information to ensure the GNU Lesser
  15 ** General Public License version 2.1 requirements will be met:
  16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  17 **
  18 ** In addition, as a special exception, Nokia gives you certain additional
  19 ** rights. These rights are described in the Nokia Qt LGPL Exception
  20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  21 **
  22 ** GNU General Public License Usage
  23 ** Alternatively, this file may be used under the terms of the GNU General
  24 ** Public License version 3.0 as published by the Free Software Foundation
  25 ** and appearing in the file LICENSE.GPL included in the packaging of this
  26 ** file. Please review the following information to ensure the GNU General
  27 ** Public License version 3.0 requirements will be met:
  28 ** http://www.gnu.org/copyleft/gpl.html.
  29 **
  30 ** Other Usage
  31 ** Alternatively, this file may be used in accordance with the terms and
  32 ** conditions contained in a signed written agreement between you and Nokia.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include <QHash>
  43
  44 #include "qxmlname.h"
  45 #include "qnamepool_p.h"
  46 #include "qabstractxmlpullprovider_p.h"
  47
  48 QT_BEGIN_NAMESPACE
  49
  50 using namespace QPatternist;
  51
  52 // TODO have example where query selects, and the events for the result are indented
  53
  54 /*!
  55   \internal
  56   \class AbstractXmlPullProvider
  57   \brief The AbstractXmlPullProvider class provides a pull-based stream interface for the XPath Data Model.
  58   \reentrant
  59   \ingroup xml-tools
  60
  61   AbstractXmlPullProvider allows a stream of items from the XPath Data Model -- essentially XML --
  62   to be iterated over. The subclass of AbstractXmlPullProvider provides the events, and the
  63   user calling next() and so on, consumes them. AbstractXmlPullProvider can be considered
  64   a forward-only, non-reversible iterator.
  65
  66   Note that the content the events describes, are not necessarily a well-formed XML document, but
  67   rather an instance of the XPath Data model, to be specific. For instance, maybe a pull provider
  68   returns two atomic values, followed by an element tree, and at the end two document nodes.
  69
  70   If you are subclassing AbstractXmlPullProvider, be careful to correctly implement
  71   the behaviors, as described for the individual members and events.
  72
  73   \sa AbstractXmlPullProvider::Event
  74  */
  75
  76 /*!
  77   \enum AbstractXmlPullProvider::Event
  78   \value StartOfInput The value AbstractXmlPullProvider::current() returns before the first call to next().
  79   \value AtomicValue an atomic value such as an \c xs:integer, \c xs:hexBinary, or \c xs:dateTime. Atomic values
  80          can only be top level items.
  81   \value StartDocument Signals the start of a document node. Note that a AbstractXmlPullProvider can provide
  82          a sequence of document nodes.
  83   \value EndDocument Signals the end of a document node. StartDocument and EndDocument are always balanced
  84          and always top-level events. For instance, StartDocument can never appear after any StartElement
  85          events that hasn't been balanced by the corresponding amount of EndElement events.
  86   \value StartElement Signals an element start tag.
  87   \value EndElement Signals the end of an element. StartElement and EndElement events are always balanced.
  88   \value Text Signals a text node. Adjacent text nodes cannot occur.
  89   \value ProcessingInstruction A processing instruction. Its name is returned from name(), and its value in stringValue().
  90   \value Comment a comment node. Its value can be retrieved with stingValue().
  91   \value Attribute Signals an attribute node. Attribute events can only appear after Namespace events, or
  92          if no such are sent, after the StartElement. In addition they must appear sequentially,
  93          and each name must be unique. The ordering of attribute events is undefined and insignificant.
  94   \value Namespace Signals a namespace binding. They occur very infrequently and are not needed for attributes
  95          and elements. Namespace events can only appear after the StartElement event. The
  96          ordering of namespace events is undefined and insignificant.
  97   \value EndOfInput When next() is called after the last event, EndOfInput is returned.
  98
  99   \sa AbstractXmlPullProvider::current()
 100  */
 101
 102 /*!
 103   Constucts a AbstractXmlPullProvider instance.
 104  */
 105 AbstractXmlPullProvider::AbstractXmlPullProvider()
 106 {
 107 }
 108
 109 /*!
 110   Destructs this AbstractXmlPullProvider.
 111  */
 112 AbstractXmlPullProvider::~AbstractXmlPullProvider()
 113 {
 114 }
 115
 116 /*!
 117   \fn Event AbstractXmlPullProvider::next() = 0;
 118   Advances this AbstractXmlPullProvider, and returns the new event.
 119
 120   \sa current()
 121  */
 122
 123 /*!
 124   \fn Event AbstractXmlPullProvider::current() const = 0;
 125   Returns the event that next() returned the last time it was called. It doesn't
 126   alter this AbstractXmlPullProvider.
 127
 128   current() may not modify this AbstractXmlPullProvider's state. Subsequent calls to current()
 129   must return the same value.
 130
 131   \sa AbstractXmlPullProvider::Event
 132  */
 133
 134 /*!
 135   \fn QName AbstractXmlPullProvider::name() const = 0;
 136   If the current event is StartElement,
 137   EndElement, ProcessingInstruction, Attribute, or Namespace, the node's name is returned.
 138
 139   If the current event is ProcessingInstruction,
 140   the processing instruction target is in in the local name.
 141
 142   If the current event is Namespace, the name's namespace URI is the namespace, and
 143   the local name is the prefix the name is binding to.
 144
 145   In all other cases, an invalid QName is returned.
 146  */
 147
 148 /*!
 149   \fn QVariant AbstractXmlPullProvider::atomicValue() const = 0;
 150
 151   If current() event is AtomicValue, the atomic value is returned as a QVariant.
 152   In all other cases, this function returns a null QVariant.
 153  */
 154
 155 /*!
 156  \fn QString AbstractXmlPullProvider::stringValue() const = 0;
 157
 158   If current() is Text, the text node's value is returned.
 159
 160   If the current() event is Comment, its value is returned. The subclasser guarantees
 161   it does not contain the string "-->".
 162
 163   If the current() event is ProcessingInstruction, its data is returned. The subclasser
 164   guarantees the data does not contain the string "?>".
 165
 166   In other cases, it returns a default constructed string.
 167   */
 168
 169 /*!
 170  \fn QHash<QXmlName, QString> AbstractXmlPullProvider::attributes() = 0;
 171
 172   If the current() is Element, the attributes of the element are returned,
 173   an empty list of attributes otherwise.
 174  */
 175
 176 QT_END_NAMESPACE
 177