1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
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 The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/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 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include <QHash>
41
42#include "qxmlname.h"
43#include "qnamepool_p.h"
44#include "qabstractxmlpullprovider_p.h"
45
46QT_BEGIN_NAMESPACE
47
48using namespace QPatternist;
49
50// TODO have example where query selects, and the events for the result are indented
51
52/*!
53 \internal
54 \class AbstractXmlPullProvider
55 \brief The AbstractXmlPullProvider class provides a pull-based stream interface for the XPath Data Model.
56 \reentrant
57 \ingroup xml-tools
58
59 AbstractXmlPullProvider allows a stream of items from the XPath Data Model -- essentially XML --
60 to be iterated over. The subclass of AbstractXmlPullProvider provides the events, and the
61 user calling next() and so on, consumes them. AbstractXmlPullProvider can be considered
62 a forward-only, non-reversible iterator.
63
64 Note that the content the events describes, are not necessarily a well-formed XML document, but
65 rather an instance of the XPath Data model, to be specific. For instance, maybe a pull provider
66 returns two atomic values, followed by an element tree, and at the end two document nodes.
67
68 If you are subclassing AbstractXmlPullProvider, be careful to correctly implement
69 the behaviors, as described for the individual members and events.
70
71 \sa AbstractXmlPullProvider::Event
72 */
73
74/*!
75 \enum AbstractXmlPullProvider::Event
76 \internal
77
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 */
105AbstractXmlPullProvider::AbstractXmlPullProvider()
106{
107}
108
109/*!
110 Destructs this AbstractXmlPullProvider.
111 */
112AbstractXmlPullProvider::~AbstractXmlPullProvider()
113{
114}
115
116/*!
117 \internal
118 \fn QPatternist::AbstractXmlPullProvider::Event QPatternist::AbstractXmlPullProvider::next() = 0
119 Advances this AbstractXmlPullProvider, and returns the new event.
120
121 \sa current()
122 */
123
124/*!
125 \internal
126 \fn QPatternist::AbstractXmlPullProvider::Event QPatternist::AbstractXmlPullProvider::current() const = 0
127 Returns the event that next() returned the last time it was called. It doesn't
128 alter this AbstractXmlPullProvider.
129
130 current() may not modify this AbstractXmlPullProvider's state. Subsequent calls to current()
131 must return the same value.
132
133 \sa AbstractXmlPullProvider::Event
134 */
135
136/*!
137 \internal
138 \fn QPatternist::AbstractXmlPullProvider::QName QPatternist::AbstractXmlPullProvider::name() const = 0
139 If the current event is StartElement,
140 EndElement, ProcessingInstruction, Attribute, or Namespace, the node's name is returned.
141
142 If the current event is ProcessingInstruction,
143 the processing instruction target is in in the local name.
144
145 If the current event is Namespace, the name's namespace URI is the namespace, and
146 the local name is the prefix the name is binding to.
147
148 In all other cases, an invalid QName is returned.
149 */
150
151/*!
152 \internal
153 \fn QVariant QPatternist::AbstractXmlPullProvider::atomicValue() const = 0
154
155 If current() event is AtomicValue, the atomic value is returned as a QVariant.
156 In all other cases, this function returns a null QVariant.
157 */
158
159/*!
160 \internal
161 \fn QString QPatternist::AbstractXmlPullProvider::stringValue() const = 0
162
163 If current() is Text, the text node's value is returned.
164
165 If the current() event is Comment, its value is returned. The subclasser guarantees
166 it does not contain the string "-->".
167
168 If the current() event is ProcessingInstruction, its data is returned. The subclasser
169 guarantees the data does not contain the string "?>".
170
171 In other cases, it returns a default constructed string.
172 */
173
174/*!
175 \internal
176 \fn QHash<QXmlName, QString> QPatternist::AbstractXmlPullProvider::attributes() = 0
177
178 If the current() is Element, the attributes of the element are returned,
179 an empty list of attributes otherwise.
180 */
181
182QT_END_NAMESPACE
183
184

source code of qtxmlpatterns/src/xmlpatterns/api/qabstractxmlpullprovider.cpp