src/xmlpatterns/api/qabstractxmlreceiver.cpp

   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 #include <QString>
  43
  44 #include "qitem_p.h"
  45
  46 #include "qabstractxmlreceiver_p.h"
  47 #include "qabstractxmlreceiver.h"
  48
  49 QT_BEGIN_NAMESPACE
  50
  51 /*!
  52   \class QAbstractXmlReceiver
  53   \brief The QAbstractXmlReceiver class provides a callback interface
  54          for transforming the output of a QXmlQuery.
  55   \reentrant
  56   \since 4.4
  57   \ingroup xml-tools
  58   \inmodule QtXmlPatterns
  59
  60   QAbstractXmlReceiver is an abstract base class that provides
  61   a callback interface for receiving an \l {XQuery Sequence}
  62   {XQuery sequence}, usually the output of an QXmlQuery, and
  63   transforming that sequence into a structure of your choosing,
  64   usually XML. Consider the example:
  65
  66   \snippet code/src_xmlpatterns_api_qabstractxmlreceiver.cpp 0
  67
  68   First it constructs a \l {QXmlQuery} {query} that gets the
  69   first paragraph from document \c index.html. Then it constructs
  70   an \l {QXmlSerializer} {XML serializer} with the \l {QXmlQuery}
  71   {query} and \l {QIODevice} {myOutputDevice} (Note the
  72   \l {QXmlSerializer} {serializer} is an \e {XML receiver},
  73   ie a subclass of QAbstractXmlReceiver). Finally, it
  74   \l {QXmlQuery::evaluateTo()} {evaluates} the
  75   \l {QXmlQuery} {query}, producing an ordered sequence of calls
  76   to the \l {QXmlSerializer} {serializer's} callback functions.
  77   The sequence of callbacks transforms the query output to XML
  78   and writes it to \l {QIODevice} {myOutputDevice}.
  79
  80   Although the example uses \l {QXmlQuery} to produce the sequence
  81   of callbacks to functions in QAbstractXmlReceiver, you can call
  82   the callback functions directly as long as your sequence of
  83   calls represents a valid \l {XQuery Sequence} {XQuery sequence}.
  84
  85   \target XQuery Sequence
  86   \section1 XQuery Sequences
  87
  88   An XQuery \a sequence is an ordered collection of zero, one,
  89   or many \e items. Each \e item is either an \e {atomic value}
  90   or a \e {node}. An \e {atomic value} is a simple data value.
  91
  92   There are six kinds of \e nodes.
  93
  94   \list
  95
  96   \li An \e {Element Node} represents an XML element.
  97
  98   \li An \e {Attribute Node} represents an XML attribute.
  99
 100   \li A \e {Document Node} represents an entire XML document.
 101
 102   \li A \e {Text Node} represents character data (element content).
 103
 104   \li A \e {Processing Instruction Node} represents an XML
 105   processing instruction, which is used in an XML document
 106   to tell the application reading the document to perform
 107   some action. A typical example is to use a processing
 108   instruction to tell the application to use a particular
 109   XSLT stylesheet to display the document.
 110
 111   \li And a \e {Comment node} represents an XML comment.
 112
 113   \endlist
 114
 115   The \e sequence of \e nodes and \e {atomic values} obeys
 116   the following rules. Note that \e {Namespace Node} refers
 117   to a special \e {Attribute Node} with name \e {xmlns}.
 118
 119   \list
 120
 121   \li Each \e node appears in the \e sequence before its children
 122   and their descendants appear.
 123
 124   \li A \e node's descendants appear in the \e sequence before
 125   any of its siblings appear.
 126
 127   \li A \e {Document Node} represents an entire document. Zero or
 128   more \e {Document Nodes} can appear in a \e sequence, but they
 129   can only be top level items (i.e., a \e {Document Node} can't
 130   be a child of another \e node.
 131
 132   \li \e {Namespace Nodes} immediately follow the \e {Element Node}
 133    with which they are associated.
 134
 135   \li \e {Attribute Nodes} immediately follow the \e {Namespace Nodes}
 136    of the element with which they are associated, or...
 137
 138    \li If there are no \e {Namespace Nodes} following an element, then
 139    the \e {Attribute Nodes} immediately follow the element.
 140
 141    \li An \e {atomic value} can only appear as a top level \e item,
 142    i.e., it can't appear as a child of a \e node.
 143
 144    \li \e {Processing Instruction Nodes} do not have children, and
 145    their parent is either a \e {Document Node} or an \e {Element
 146    Node}.
 147
 148    \li \e {Comment Nodes} do not have children, and
 149    their parent is either a \e {Document Node} or an \e {Element
 150    Node}.
 151
 152   \endlist
 153
 154   The \e sequence of \e nodes and \e {atomic values} is sent to
 155   an QAbstractXmlReceiver (QXmlSerializer in
 156   the example above) as a sequence of calls to the receiver's
 157   callback functions. The mapping of callback functions to
 158   sequence items is as follows.
 159
 160   \list
 161
 162   \li startDocument() and endDocument() are called for each
 163   \e {Document Node} in the \e sequence. endDocument() is not
 164   called until all the \e {Document Node's} children have
 165   appeared in the \e sequence.
 166
 167   \li startElement() and endElement() are called for each
 168   \e {Element Node}. endElement() is not called until all the
 169   \e {Element Node's} children have appeared in the \e sequence.
 170
 171   \li attribute() is called for each \e {Attribute Node}.
 172
 173   \li comment() is called for each \e {Comment Node}.
 174
 175   \li characters() is called for each \e {Text Node}.
 176
 177   \li processingInstruction() is called for each \e {Processing
 178   Instruction Node}.
 179
 180   \li namespaceBinding() is called for each \e {Namespace Node}.
 181
 182   \li atomicValue() is called for each \e {atomic value}.
 183
 184   \endlist
 185
 186   For a complete explanation of XQuery sequences, visit
 187   \l {http://www.w3.org/TR/xpath-datamodel/}{XQuery Data Model}.
 188
 189   \sa {http://www.w3.org/TR/xpath-datamodel/}{W3C XQuery 1.0 and XPath 2.0 Data Model (XDM)}
 190   \sa QXmlSerializer
 191   \sa QXmlResultItems
 192  */
 193
 194 template<const QXmlNodeModelIndex::Axis axis>
 195 void QAbstractXmlReceiver::sendFromAxis(const QXmlNodeModelIndex &node)
 196 {
 197     Q_ASSERT(!node.isNull());
 198     const QXmlNodeModelIndex::Iterator::Ptr it(node.iterate(axis));
 199     QXmlNodeModelIndex next(it->next());
 200
 201     while(!next.isNull())
 202     {
 203         sendAsNode(next);
 204         next = it->next();
 205     }
 206 }
 207
 208 /*!
 209  \internal
 210  */
 211 QAbstractXmlReceiver::QAbstractXmlReceiver(QAbstractXmlReceiverPrivate *d)
 212   : d_ptr(d)
 213 {
 214 }
 215
 216 /*!
 217   Constructs an abstract xml receiver.
 218  */
 219 QAbstractXmlReceiver::QAbstractXmlReceiver() : d_ptr(0)
 220 {
 221 }
 222
 223 /*!
 224   Destroys the xml receiver.
 225  */
 226 QAbstractXmlReceiver::~QAbstractXmlReceiver()
 227 {
 228 }
 229
 230 /*!
 231   \fn void QAbstractXmlReceiver::startElement(const QXmlName &name)
 232
 233   This callback is called when a new element node appears
 234   in the \l {XQuery Sequence} {sequence}. \a name is the
 235   valid \l {QXmlName} {name} of the node element.
 236  */
 237
 238 /*
 239 ### Qt 5:
 240
 241 Consider how source locations should be communicated. Maybe every signature
 242 should be extended by adding "qint64 line = -1, qint64 column = -1".
 243  */
 244
 245 /*!
 246   \fn void QAbstractXmlReceiver::endElement()
 247
 248   This callback is called when the end of an element node
 249   appears in the \l {XQuery Sequence} {sequence}.
 250 */
 251
 252 /*!
 253   \fn void QAbstractXmlReceiver::attribute(const QXmlName &name,
 254                                            const QStringRef &value)
 255   This callback is called when an attribute node
 256   appears in the \l {XQuery Sequence} {sequence}.
 257   \a name is the \l {QXmlName} {attribute name} and
 258   the \a value string contains the attribute value.
 259  */
 260
 261 /*!
 262   \fn void QAbstractXmlReceiver::comment(const QString &value)
 263
 264   This callback is called when a comment node appears
 265   in the \l {XQuery Sequence} {sequence}. The \a value
 266   is the comment text, which must not contain the string
 267   "--".
 268  */
 269
 270 /*!
 271   \fn void QAbstractXmlReceiver::characters(const QStringRef &value)
 272
 273   This callback is called when a text node appears in the
 274   \l {XQuery Sequence} {sequence}. The \a value contains
 275   the text. Adjacent text nodes may not occur in the
 276   \l {XQuery Sequence} {sequence}, i.e., this callback must not
 277   be called twice in a row.
 278  */
 279
 280 /*!
 281   \fn void QAbstractXmlReceiver::startDocument()
 282
 283   This callback is called when a document node appears
 284   in the \l {XQuery Sequence} {sequence}.
 285  */
 286
 287 /*
 288 ### Qt 5:
 289
 290 Change
 291     virtual void startDocument() = 0;
 292
 293 To:
 294     virtual void startDocument(const QUrl &uri) = 0;
 295
 296 Such that it allows the document URI to be communicated. The contract would
 297 allow null QUrls.
 298 */
 299
 300 /*!
 301   \fn void QAbstractXmlReceiver::endDocument()
 302
 303   This callback is called when the end of a document node
 304   appears in the \l {XQuery Sequence} {sequence}.
 305  */
 306
 307 /*!
 308   \fn void QAbstractXmlReceiver::processingInstruction(const QXmlName &target,
 309                                                        const QString &value)
 310
 311   This callback is called when a processing instruction
 312   appears in the \l {XQuery Sequence} {sequence}.
 313   A processing instruction is used in an XML document
 314   to tell the application reading the document to
 315   perform some action. A typical example is to use a
 316   processing instruction to tell the application to use a
 317   particular XSLT stylesheet to process the document.
 318
 319   \quotefile patternist/xmlStylesheet.xq
 320
 321   \a target is the \l {QXmlName} {name} of the processing
 322   instruction. Its \e prefix and \e {namespace URI} must both
 323   be empty. Its \e {local name} is the target. In the above
 324   example, the name is \e {xml-stylesheet}.
 325
 326   The \a value specifies the action to be taken. Note that
 327   the \a value must not contain the string "?>". In the above
 328   example, the \a value is \e{type="test/xsl" href="formatter.xsl}.
 329
 330   Generally, use of processing instructions should be avoided,
 331   because they are not namespace aware and in many contexts
 332   are stripped out anyway. Processing instructions can often
 333   be replaced with elements from a custom namespace.
 334  */
 335
 336 /*!
 337   \fn void QAbstractXmlReceiver::atomicValue(const QVariant &value)
 338
 339   This callback is called when an atomic value appears in the \l
 340   {XQuery Sequence} {sequence}. The \a value is a simple \l {QVariant}
 341   {data value}. It is guaranteed to be \l {QVariant::isValid()}
 342   {valid}.
 343  */
 344
 345 /*!
 346   \fn virtual void QAbstractXmlReceiver::namespaceBinding(const QXmlName &name)
 347
 348   This callback is called when a namespace binding is in scope of an
 349   element. A namespace is defined by a URI. In the \l {QXmlName}
 350   \a name, the value of \l {QXmlName::namespaceUri()} is that URI. The
 351   value of \l {QXmlName::prefix()} is the prefix that the URI is bound
 352   to. The local name is insignificant and can be an arbitrary value.
 353  */
 354
 355 /*!
 356   \internal
 357
 358    Treats \a outputItem as a node and calls the appropriate function,
 359    e.g., attribute() or comment(), depending on its
 360    QXmlNodeModelIndex::NodeKind.
 361
 362    This is a helper function that subclasses can use to multiplex
 363    Nodes received via item().
 364  */
 365 void QAbstractXmlReceiver::sendAsNode(const QPatternist::Item &outputItem)
 366 {
 367     Q_ASSERT(outputItem);
 368     Q_ASSERT(outputItem.isNode());
 369     const QXmlNodeModelIndex asNode = outputItem.asNode();
 370
 371     switch(asNode.kind())
 372     {
 373         case QXmlNodeModelIndex::Attribute:
 374         {
 375             const QString &v = outputItem.stringValue();
 376             attribute(asNode.name(), QStringRef(&v));
 377             return;
 378         }
 379         case QXmlNodeModelIndex::Element:
 380         {
 381             startElement(asNode.name());
 382
 383             /* First the namespaces, then attributes, then the children. */
 384             asNode.sendNamespaces(this);
 385             sendFromAxis<QXmlNodeModelIndex::AxisAttribute>(asNode);
 386             sendFromAxis<QXmlNodeModelIndex::AxisChild>(asNode);
 387
 388             endElement();
 389
 390             return;
 391         }
 392         case QXmlNodeModelIndex::Text:
 393         {
 394             const QString &v = asNode.stringValue();
 395             characters(QStringRef(&v));
 396             return;
 397         }
 398         case QXmlNodeModelIndex::ProcessingInstruction:
 399         {
 400             processingInstruction(asNode.name(), outputItem.stringValue());
 401             return;
 402         }
 403         case QXmlNodeModelIndex::Comment:
 404         {
 405             comment(outputItem.stringValue());
 406             return;
 407         }
 408         case QXmlNodeModelIndex::Document:
 409         {
 410             startDocument();
 411             sendFromAxis<QXmlNodeModelIndex::AxisChild>(asNode);
 412             endDocument();
 413             return;
 414         }
 415         case QXmlNodeModelIndex::Namespace:
 416             Q_ASSERT_X(false, Q_FUNC_INFO, "Not implemented");
 417     }
 418
 419     Q_ASSERT_X(false, Q_FUNC_INFO,
 420                QString::fromLatin1("Unknown node type: %1").arg(asNode.kind()).toUtf8().constData());
 421 }
 422
 423 /*!
 424   \internal
 425
 426    This function may be called instead of characters() if, and only if,
 427    \a value consists only of whitespace.
 428
 429    The caller gurantees that \a value is not empty.
 430
 431    \e Whitespace refers to a sequence of characters that are either
 432    spaces, tabs, or newlines, in any order. In other words, not all
 433    the Unicode whitespace category is considered whitespace here.
 434
 435    However, there is no guarantee or requirement that whitespaceOnly()
 436    is called for text nodes containing whitespace only. characters()
 437    may be called just as well. This is why the default implementation
 438    for whitespaceOnly() calls characters().
 439
 440    \sa characters()
 441  */
 442 void QAbstractXmlReceiver::whitespaceOnly(const QStringRef &value)
 443 {
 444     Q_ASSERT_X(value.toString().trimmed().isEmpty(), Q_FUNC_INFO,
 445                "The caller must guarantee only whitespace is passed. Use characters() in other cases.");
 446     const QString &v = value.toString();
 447     characters(QStringRef(&v));
 448 }
 449
 450 /*!
 451   \internal
 452  */
 453 void QAbstractXmlReceiver::item(const QPatternist::Item &item)
 454 {
 455     if(item.isNode())
 456         return sendAsNode(item);
 457     else
 458         atomicValue(QPatternist::AtomicValue::toQt(item.asAtomicValue()));
 459 }
 460
 461 /*!
 462  \fn void QAbstractXmlReceiver::startOfSequence()
 463
 464  This callback is called once only, right before the
 465  \l {XQuery Sequence} {sequence} begins.
 466  */
 467
 468 /*!
 469   \fn void QAbstractXmlReceiver::endOfSequence()
 470
 471  This callback is called once only, right after the
 472  \l {XQuery Sequence} {sequence} ends.
 473  */
 474
 475 QT_END_NAMESPACE
 476