/****************************************************************************+
−
**+
−
** 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 QtXmlPatterns module 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$+
−
**+
−
****************************************************************************/+
−
+
−
#include <QString>+
−
+
−
#include "qitem_p.h"+
−
+
−
#include "qabstractxmlreceiver_p.h"+
−
#include "qabstractxmlreceiver.h"+
−
+
−
QT_BEGIN_NAMESPACE+
−
+
−
/*!+
−
  \class QAbstractXmlReceiver+
−
  \brief The QAbstractXmlReceiver class provides a callback interface+
−
         for transforming the output of a QXmlQuery.+
−
  \reentrant+
−
  \since 4.4+
−
  \ingroup xml-tools+
−
+
−
  QAbstractXmlReceiver is an abstract base class that provides+
−
  a callback interface for receiving an \l {XQuery Sequence}+
−
  {XQuery sequence}, usually the output of an QXmlQuery, and+
−
  transforming that sequence into a structure of your choosing,+
−
  usually XML. Consider the example:+
−
+
−
  \snippet doc/src/snippets/code/src_xmlpatterns_api_qabstractxmlreceiver.cpp 0+
−
+
−
  First it constructs a \l {QXmlQuery} {query} that gets the+
−
  first paragraph from document \c index.html. Then it constructs+
−
  an \l {QXmlSerializer} {XML serializer} with the \l {QXmlQuery}+
−
  {query} and \l {QIODevice} {myOutputDevice} (Note the+
−
  \l {QXmlSerializer} {serializer} is an \e {XML receiver},+
−
  ie a subclass of QAbstractXmlReceiver). Finally, it+
−
  \l {QXmlQuery::evaluateTo()} {evaluates} the+
−
  \l {QXmlQuery} {query}, producing an ordered sequence of calls+
−
  to the \l {QXmlSerializer} {serializer's} callback functions.+
−
  The sequence of callbacks transforms the query output to XML+
−
  and writes it to \l {QIODevice} {myOutputDevice}.+
−
+
−
  Although the example uses \l {QXmlQuery} to produce the sequence+
−
  of callbacks to functions in QAbstractXmlReceiver, you can call+
−
  the callback functions directly as long as your sequence of+
−
  calls represents a valid \l {XQuery Sequence} {XQuery sequence}.+
−
+
−
  \target XQuery Sequence+
−
  \section1 XQuery Sequences+
−
+
−
  An XQuery \a sequence is an ordered collection of zero, one,+
−
  or many \e items. Each \e item is either an \e {atomic value}+
−
  or a \e {node}. An \e {atomic value} is a simple data value.+
−
+
−
  There are six kinds of \e nodes.+
−
+
−
  \list+
−
+
−
  \o An \e {Element Node} represents an XML element.+
−
+
−
  \o An \e {Attribute Node} represents an XML attribute.+
−
+
−
  \o A \e {Document Node} represents an entire XML document.+
−
+
−
  \o A \e {Text Node} represents character data (element content).+
−
+
−
  \o A \e {Processing Instruction Node} represents an XML+
−
  processing instruction, which is used in an XML document+
−
  to tell the application reading the document to perform+
−
  some action. A typical example is to use a processing+
−
  instruction to tell the application to use a particular+
−
  XSLT stylesheet to display the document.+
−
+
−
  \o And a \e {Comment node} represents an XML comment.+
−
+
−
  \endlist+
−
+
−
  The \e sequence of \e nodes and \e {atomic values} obeys+
−
  the following rules. Note that \e {Namespace Node} refers+
−
  to a special \e {Attribute Node} with name \e {xmlns}.+
−
+
−
  \list+
−
+
−
  \o Each \e node appears in the \e sequence before its children+
−
  and their descendants appear.+
−
+
−
  \o A \e node's descendants appear in the \e sequence before+
−
  any of its siblings appear.+
−
+
−
  \o A \e {Document Node} represents an entire document. Zero or+
−
  more \e {Document Nodes} can appear in a \e sequence, but they+
−
  can only be top level items (i.e., a \e {Document Node} can't+
−
  be a child of another \e node.+
−
+
−
  \o \e {Namespace Nodes} immediately follow the \e {Element Node}+
−
   with which they are associated.+
−
+
−
  \o \e {Attribute Nodes} immediately follow the \e {Namespace Nodes}+
−
   of the element with which they are associated, or...+
−
+
−
   \o If there are no \e {Namespace Nodes} following an element, then+
−
   the \e {Attribute Nodes} immediately follow the element.+
−
+
−
   \o An \e {atomic value} can only appear as a top level \e item,+
−
   i.e., it can't appear as a child of a \e node.+
−
+
−
   \o \e {Processing Instruction Nodes} do not have children, and+
−
   their parent is either a \e {Document Node} or an \e {Element+
−
   Node}.+
−
+
−
   \o \e {Comment Nodes} do not have children, and+
−
   their parent is either a \e {Document Node} or an \e {Element+
−
   Node}.+
−
+
−
  \endlist+
−
+
−
  The \e sequence of \e nodes and \e {atomic values} is sent to+
−
  an QAbstractXmlReceiver (QXmlSerializer in+
−
  the example above) as a sequence of calls to the receiver's+
−
  callback functions. The mapping of callback functions to+
−
  sequence items is as follows.+
−
+
−
  \list+
−
+
−
  \o startDocument() and endDocument() are called for each+
−
  \e {Document Node} in the \e sequence. endDocument() is not+
−
  called until all the \e {Document Node's} children have+
−
  appeared in the \e sequence.+
−
+
−
  \o startElement() and endElement() are called for each+
−
  \e {Element Node}. endElement() is not called until all the+
−
  \e {Element Node's} children have appeared in the \e sequence.+
−
+
−
  \o attribute() is called for each \e {Attribute Node}.+
−
+
−
  \o comment() is called for each \e {Comment Node}.+
−
+
−
  \o characters() is called for each \e {Text Node}.+
−
+
−
  \o processingInstruction() is called for each \e {Processing+
−
  Instruction Node}.+
−
+
−
  \o namespaceBinding() is called for each \e {Namespace Node}.+
−
+
−
  \o atomicValue() is called for each \e {atomic value}.+
−
+
−
  \endlist+
−
+
−
  For a complete explanation of XQuery sequences, visit+
−
  \l {http://www.w3.org/TR/xpath-datamodel/}{XQuery Data Model}.+
−
+
−
  \sa {http://www.w3.org/TR/xpath-datamodel/}{W3C XQuery 1.0 and XPath 2.0 Data Model (XDM)}+
−
  \sa QXmlSerializer+
−
  \sa QXmlResultItems+
−
 */+
−
+
−
template<const QXmlNodeModelIndex::Axis axis>+
−
void QAbstractXmlReceiver::sendFromAxis(const QXmlNodeModelIndex &node)+
−
{+
−
    Q_ASSERT(!node.isNull());+
−
    const QXmlNodeModelIndex::Iterator::Ptr it(node.iterate(axis));+
−
    QXmlNodeModelIndex next(it->next());+
−
+
−
    while(!next.isNull())+
−
    {+
−
        sendAsNode(next);+
−
        next = it->next();+
−
    }+
−
}+
−
+
−
/*!+
−
 \internal+
−
 */+
−
QAbstractXmlReceiver::QAbstractXmlReceiver(QAbstractXmlReceiverPrivate *d)+
−
  : d_ptr(d)+
−
{+
−
}+
−
+
−
/*!+
−
  Constructs an abstract xml receiver.+
−
 */+
−
QAbstractXmlReceiver::QAbstractXmlReceiver() : d_ptr(0)+
−
{+
−
}+
−
+
−
/*!+
−
  Destroys the xml receiver.+
−
 */+
−
QAbstractXmlReceiver::~QAbstractXmlReceiver()+
−
{+
−
}+
−
+
−
/*!+
−
  \fn void QAbstractXmlReceiver::startElement(const QXmlName &name)+
−
+
−
  This callback is called when a new element node appears+
−
  in the \l {XQuery Sequence} {sequence}. \a name is the+
−
  valid \l {QXmlName} {name} of the node element.+
−
 */+
−
+
−
/*+
−
### Qt 5:+
−
+
−
Consider how source locations should be communicated. Maybe every signature+
−
should be extended by adding "qint64 line = -1, qint64 column = -1".+
−
 */+
−
+
−
/*!+
−
  \fn void QAbstractXmlReceiver::endElement()+
−
+
−
  This callback is called when the end of an element node+
−
  appears in the \l {XQuery Sequence} {sequence}.+
−
*/+
−
+
−
/*!+
−
  \fn void QAbstractXmlReceiver::attribute(const QXmlName &name,+
−
                                           const QStringRef &value)+
−
  This callback is called when an attribute node+
−
  appears in the \l {XQuery Sequence} {sequence}.+
−
  \a name is the \l {QXmlName} {attribute name} and+
−
  the \a value string contains the attribute value.+
−
 */+
−
+
−
/*!+
−
  \fn void QAbstractXmlReceiver::comment(const QString &value)+
−
+
−
  This callback is called when a comment node appears+
−
  in the \l {XQuery Sequence} {sequence}. The \a value+
−
  is the comment text, which must not contain the string+
−
  "--".+
−
 */+
−
+
−
/*!+
−
  \fn void QAbstractXmlReceiver::characters(const QStringRef &value)+
−
+
−
  This callback is called when a text node appears in the+
−
  \l {XQuery Sequence} {sequence}. The \a value contains+
−
  the text. Adjacent text nodes may not occur in the+
−
  \l {XQuery Sequence} {sequence}, i.e., this callback must not+
−
  be called twice in a row.+
−
 */+
−
+
−
/*!+
−
  \fn void QAbstractXmlReceiver::startDocument()+
−
+
−
  This callback is called when a document node appears+
−
  in the \l {XQuery Sequence} {sequence}.+
−
 */+
−
+
−
/*+
−
### Qt 5:+
−
+
−
Change+
−
    virtual void startDocument() = 0;+
−
+
−
To:+
−
    virtual void startDocument(const QUrl &uri) = 0;+
−
+
−
Such that it allows the document URI to be communicated. The contract would+
−
allow null QUrls.+
−
*/+
−
+
−
/*!+
−
  \fn void QAbstractXmlReceiver::endDocument()+
−
+
−
  This callback is called when the end of a document node+
−
  appears in the \l {XQuery Sequence} {sequence}.+
−
 */+
−
+
−
/*!+
−
  \fn void QAbstractXmlReceiver::processingInstruction(const QXmlName &target,+
−
                                                       const QString &value)+
−
+
−
  This callback is called when a processing instruction+
−
  appears in the \l {XQuery Sequence} {sequence}.+
−
  A processing instruction is used in an XML document+
−
  to tell the application reading the document to+
−
  perform some action. A typical example is to use a+
−
  processing instruction to tell the application to use a+
−
  particular XSLT stylesheet to process the document.+
−
+
−
  \quotefile doc/src/snippets/patternist/xmlStylesheet.xq+
−
+
−
  \a target is the \l {QXmlName} {name} of the processing+
−
  instruction. Its \e prefix and \e {namespace URI} must both+
−
  be empty. Its \e {local name} is the target. In the above+
−
  example, the name is \e {xml-stylesheet}.+
−
+
−
  The \a value specifies the action to be taken. Note that+
−
  the \a value must not contain the string "?>". In the above+
−
  example, the \a value is \e{type="test/xsl" href="formatter.xsl}.+
−
+
−
  Generally, use of processing instructions should be avoided,+
−
  because they are not namespace aware and in many contexts+
−
  are stripped out anyway. Processing instructions can often+
−
  be replaced with elements from a custom namespace.+
−
 */+
−
+
−
/*!+
−
  \fn void QAbstractXmlReceiver::atomicValue(const QVariant &value)+
−
+
−
  This callback is called when an atomic value appears in the \l+
−
  {XQuery Sequence} {sequence}. The \a value is a simple \l {QVariant}+
−
  {data value}. It is guaranteed to be \l {QVariant::isValid()}+
−
  {valid}.+
−
 */+
−
+
−
/*!+
−
  \fn virtual void QAbstractXmlReceiver::namespaceBinding(const QXmlName &name)+
−
+
−
  This callback is called when a namespace binding is in scope of an+
−
  element. A namespace is defined by a URI. In the \l {QXmlName}+
−
  \a name, the value of \l {QXmlName::namespaceUri()} is that URI. The+
−
  value of \l {QXmlName::prefix()} is the prefix that the URI is bound+
−
  to. The local name is insignificant and can be an arbitrary value.+
−
 */+
−
+
−
/*!+
−
  \internal+
−
+
−
   Treats \a outputItem as a node and calls the appropriate function,+
−
   e.g., attribute() or comment(), depending on its+
−
   QXmlNodeModelIndex::NodeKind.+
−
+
−
   This is a helper function that subclasses can use to multiplex+
−
   Nodes received via item().+
−
 */+
−
void QAbstractXmlReceiver::sendAsNode(const QPatternist::Item &outputItem)+
−
{+
−
    Q_ASSERT(outputItem);+
−
    Q_ASSERT(outputItem.isNode());+
−
    const QXmlNodeModelIndex asNode = outputItem.asNode();+
−
+
−
    switch(asNode.kind())+
−
    {+
−
        case QXmlNodeModelIndex::Attribute:+
−
        {+
−
            const QString &v = outputItem.stringValue();+
−
            attribute(asNode.name(), QStringRef(&v));+
−
            return;+
−
        }+
−
        case QXmlNodeModelIndex::Element:+
−
        {+
−
            startElement(asNode.name());+
−
+
−
            /* First the namespaces, then attributes, then the children. */+
−
            asNode.sendNamespaces(this);+
−
            sendFromAxis<QXmlNodeModelIndex::AxisAttribute>(asNode);+
−
            sendFromAxis<QXmlNodeModelIndex::AxisChild>(asNode);+
−
+
−
            endElement();+
−
+
−
            return;+
−
        }+
−
        case QXmlNodeModelIndex::Text:+
−
        {+
−
            const QString &v = asNode.stringValue();+
−
            characters(QStringRef(&v));+
−
            return;+
−
        }+
−
        case QXmlNodeModelIndex::ProcessingInstruction:+
−
        {+
−
            processingInstruction(asNode.name(), outputItem.stringValue());+
−
            return;+
−
        }+
−
        case QXmlNodeModelIndex::Comment:+
−
        {+
−
            comment(outputItem.stringValue());+
−
            return;+
−
        }+
−
        case QXmlNodeModelIndex::Document:+
−
        {+
−
            startDocument();+
−
            sendFromAxis<QXmlNodeModelIndex::AxisChild>(asNode);+
−
            endDocument();+
−
            return;+
−
        }+
−
        case QXmlNodeModelIndex::Namespace:+
−
            Q_ASSERT_X(false, Q_FUNC_INFO, "Not implemented");+
−
    }+
−
+
−
    Q_ASSERT_X(false, Q_FUNC_INFO,+
−
               QString::fromLatin1("Unknown node type: %1").arg(asNode.kind()).toUtf8().constData());+
−
}+
−
+
−
/*!+
−
  \internal+
−
+
−
   This function may be called instead of characters() if, and only if,+
−
   \a value consists only of whitespace.+
−
+
−
   The caller gurantees that \a value is not empty.+
−
+
−
   \e Whitespace refers to a sequence of characters that are either+
−
   spaces, tabs, or newlines, in any order. In other words, not all+
−
   the Unicode whitespace category is considered whitespace here.+
−
+
−
   However, there is no guarantee or requirement that whitespaceOnly()+
−
   is called for text nodes containing whitespace only. characters()+
−
   may be called just as well. This is why the default implementation+
−
   for whitespaceOnly() calls characters().+
−
+
−
   \sa characters()+
−
 */+
−
void QAbstractXmlReceiver::whitespaceOnly(const QStringRef &value)+
−
{+
−
    Q_ASSERT_X(value.toString().trimmed().isEmpty(), Q_FUNC_INFO,+
−
               "The caller must guarantee only whitespace is passed. Use characters() in other cases.");+
−
    const QString &v = value.toString();+
−
    characters(QStringRef(&v));+
−
}+
−
+
−
/*!+
−
  \internal+
−
 */+
−
void QAbstractXmlReceiver::item(const QPatternist::Item &item)+
−
{+
−
    if(item.isNode())+
−
        return sendAsNode(item);+
−
    else+
−
        atomicValue(QPatternist::AtomicValue::toQt(item.asAtomicValue()));+
−
}+
−
+
−
/*!+
−
 \fn void QAbstractXmlReceiver::startOfSequence()+
−
+
−
 This callback is called once only, right before the+
−
 \l {XQuery Sequence} {sequence} begins.+
−
 */+
−
+
−
/*!+
−
  \fn void QAbstractXmlReceiver::endOfSequence()+
−
+
−
 This callback is called once only, right after the+
−
 \l {XQuery Sequence} {sequence} ends.+
−
 */+
−
+
−
QT_END_NAMESPACE+
−
+
−