src/xmlpatterns/expr/qexternalvariableloader_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_ExternalVariableLoader_H
  53 #define Patternist_ExternalVariableLoader_H
  54
  55 #include <private/qitem_p.h>
  56 #include <private/qsequencetype_p.h>
  57 #include <QXmlName>
  58
  59 QT_BEGIN_HEADER
  60
  61 QT_BEGIN_NAMESPACE
  62
  63 namespace QPatternist
  64 {
  65     class DynamicContext;
  66
  67     /**
  68      * @short Responsible for loading and declaring available external variables.
  69      *
  70      * An external variable in XQuery is a global variable that has been declared to receive
  71      * its value from the XQuery implementation, as opposed to an initializing expression. Here
  72      * is an example of a query with an external variable declaration, followed by a ordinary
  73      * global variable:
  74      *
  75      * <tt> declare variable $theName external;
  76      * declare variable $theName := "the value";
  77      * "And here's the query body(a string literal)"</tt>
  78      *
  79      * An external variable declaration can also specify a sequence type:
  80      *
  81      * <tt>declare variable $theName as xs:integer external;</tt>
  82      *
  83      * This class allows the user to supply the values to external variables. When
  84      * an external variable declaration occur in the query,
  85      * announceExternalVariable() is called.
  86      *
  87      * @ingroup Patternist_xdm
  88      * @author Frans Englich <frans.englich@nokia.com>
  89      */
  90     class Q_AUTOTEST_EXPORT ExternalVariableLoader : public QSharedData
  91     {
  92     public:
  93         typedef QExplicitlySharedDataPointer<ExternalVariableLoader> Ptr;
  94         inline ExternalVariableLoader() {}
  95
  96         virtual ~ExternalVariableLoader();
  97
  98         /**
  99          * Called when Patternist encounters an external variable in the query. It is guaranteed
 100          * to be called once for each external variable appearing in a query module.
 101          *
 102          * @param name the name of the variable. Quaranteed to never be @c null.
 103          * @param declaredType the type that the user declared the variable to be of. Whether
 104          * this type matches the actual value of the variable or not is irrelevant. Patternist
 105          * will do the necessary error handling based on the sequence type that is returned from
 106          * this function. If the user didn't declare a type, the type is <tt>item()*</tt>(zero or
 107          * more items). Quaranteed to never be @c null.
 108          * @returns the sequence type of the value this ExternalVariableLoader actually supplies. However,
 109          * if the ExternalVariableLoader knows it cannot supply a variable by this name, @c null should be
 110          * returned.
 111          */
 112         virtual SequenceType::Ptr announceExternalVariable(const QXmlName name,
 113                                                            const SequenceType::Ptr &declaredType);
 114
 115         /**
 116          * This function is called at runtime when the external variable by name @p name needs
 117          * to be evaluated. It is not defined how many times this function will be called. It
 118          * depends on aspects such as how the query was optimized.
 119          *
 120          * @param name the name of the variable. Quaranteed to never be @c null.
 121          * @param context the DynamicContext.
 122          * @returns the value of the variable. Remember that this value must match the
 123          * sequence type returned from announceExternalVariable() for the same name.
 124          */
 125         virtual Item::Iterator::Ptr evaluateSequence(const QXmlName name,
 126                                                      const QExplicitlySharedDataPointer<DynamicContext> &context);
 127
 128         virtual Item evaluateSingleton(const QXmlName name,
 129                                             const QExplicitlySharedDataPointer<DynamicContext> &context);
 130         virtual bool evaluateEBV(const QXmlName name,
 131                                  const QExplicitlySharedDataPointer<DynamicContext> &context);
 132     };
 133 }
 134
 135 QT_END_NAMESPACE
 136
 137 QT_END_HEADER
 138
 139 #endif