qgsexpression.h

Go to the documentation of this file.

/***************************************************************************
                               qgsexpression.h
                             -------------------
    begin                : August 2011
    copyright            : (C) 2011 Martin Dobias
    email                : wonder.sk at gmail dot com
 ***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/
 
#ifndef QGSEXPRESSION_H
#define QGSEXPRESSION_H
 
#include <functional>
 
#include "qgis.h"
#include "qgis_core.h"
#include "qgsexpressionnode.h"
#include "qgsinterval.h"
#include "qgsproject.h"
#include "qgsthreadingutils.h"
 
#include <QCoreApplication>
#include <QDomDocument>
#include <QList>
#include <QMetaType>
#include <QReadWriteLock>
#include <QRecursiveMutex>
#include <QSet>
#include <QString>
#include <QStringList>
#include <QVariant>
 
using namespace Qt::StringLiterals;
 
class QgsFeature;
class QgsGeometry;
class QgsOgcUtils;
class QgsVectorLayer;
class QgsVectorDataProvider;
class QgsField;
class QgsFields;
class QgsDistanceArea;
class QDomElement;
class QgsExpressionContext;
class QgsExpressionPrivate;
class QgsExpressionFunction;
 
#ifndef SIP_RUN
struct HelpArg
{
    HelpArg( const QString &arg, const QString &desc, bool descOnly = false, bool syntaxOnly = false, bool optional = false, const QString &defaultVal = QString() )
      : mArg( arg )
      , mDescription( desc )
      , mDescOnly( descOnly )
      , mSyntaxOnly( syntaxOnly )
      , mOptional( optional )
      , mDefaultVal( defaultVal )
    {}
 
    QString mArg;
    QString mDescription;
    bool mDescOnly;
    bool mSyntaxOnly;
    bool mOptional;
    QString mDefaultVal;
};
 
struct HelpExample
{
    HelpExample( const QString &expression, const QString &returns, const QString &note = QString() )
      : mExpression( expression )
      , mReturns( returns )
      , mNote( note )
    {}
 
    QString mExpression;
    QString mReturns;
    QString mNote;
};
 
 
struct HelpVariant
{
    HelpVariant(
      const QString &name,
      const QString &description,
      const QList<HelpArg> &arguments = QList<HelpArg>(),
      bool variableLenArguments = false,
      const QList<HelpExample> &examples = QList<HelpExample>(),
      const QString &notes = QString(),
      const QStringList &tags = QStringList()
    )
      : mName( name )
      , mDescription( description )
      , mArguments( arguments )
      , mVariableLenArguments( variableLenArguments )
      , mExamples( examples )
      , mNotes( notes )
      , mTags( tags )
    {}
 
    QString mName;
    QString mDescription;
    QList<HelpArg> mArguments;
    bool mVariableLenArguments;
    QList<HelpExample> mExamples;
    QString mNotes;
    QStringList mTags;
};
 
 
struct Help
{
    Help() = default;
 
    Help( const QString &name, const QString &type, const QString &description, const QList<HelpVariant> &variants )
      : mName( name )
      , mType( type )
      , mDescription( description )
      , mVariants( variants )
    {}
 
    QString mName;
    QString mType;
    QString mDescription;
    QList<HelpVariant> mVariants;
};
 
typedef QHash<QString, Help> HelpTextHash;

#endif

class CORE_EXPORT QgsExpression
{
    Q_DECLARE_TR_FUNCTIONS( QgsExpression )
  public:
#ifndef SIP_RUN
    using SharedFunctionPtr = std::shared_ptr<QgsExpressionFunction>;

    class CORE_EXPORT SharedFunctionPtrList : public QList< SharedFunctionPtr >
    {
      public:
        int functionIndex( const QString &name ) const;

        SharedFunctionPtr getFunction( int index ) const;

        void updateFunctionNameMap();
 
      private:
        QMap< QString, int> mFunctionIndexMap;
    };
 
    using FunctionListSnapshot = std::shared_ptr< const SharedFunctionPtrList >;
#endif

    struct CORE_EXPORT ParserError
    {
        enum ParserErrorType
        {
          Unknown = 0,               
          FunctionUnknown = 1,       
          FunctionWrongArgs = 2,     
          FunctionInvalidParams = 3, 
          FunctionNamedArgsError = 4 
        };

        QgsExpression::ParserError::ParserErrorType errorType = QgsExpression::ParserError::ParserErrorType::Unknown;

        QString errorMsg;

        int firstLine = 0;

        int firstColumn = 0;

        int lastLine = 0;

        int lastColumn = 0;
    };

    QgsExpression( const QString &expr );

    QgsExpression( const QgsExpression &other );

    QgsExpression &operator=( const QgsExpression &other );

    operator QString() const SIP_SKIP;

    QgsExpression();
 
    ~QgsExpression();

    bool operator==( const QgsExpression &other ) const;

    bool isValid() const;

    bool hasParserError() const;
    QString parserErrorString() const;

    QList<QgsExpression::ParserError> parserErrors() const;

    const QgsExpressionNode *rootNode() const;

    bool prepare( const QgsExpressionContext *context );

    QSet<QString> referencedColumns() const;

    QSet<QString> referencedVariables() const;

    QSet<QString> referencedFunctions() const;
 
#ifndef SIP_RUN

    QList<const QgsExpressionNode *> nodes() const;

    template<class T> QList<const T *> findNodes() const
    {
      QList<const T *> lst;
      const QList<const QgsExpressionNode *> allNodes( nodes() );
      for ( const auto &node : allNodes )
      {
        const T *n = dynamic_cast<const T *>( node );
        if ( n )
          lst << n;
      }
      return lst;
    }
#endif

    QSet<int> referencedAttributeIndexes( const QgsFields &fields ) const;

    bool needsGeometry() const;
 
    // evaluation

    QVariant evaluate();

    QVariant evaluate( const QgsExpressionContext *context );

    bool hasEvalError() const;
    QString evalErrorString() const;
    void setEvalErrorString( const QString &str );

    bool isField() const;

    static int expressionToLayerFieldIndex( const QString &expression, const QgsVectorLayer *layer );

    static QString quoteFieldExpression( const QString &expression, const QgsVectorLayer *layer );

    static bool checkExpression( const QString &text, const QgsExpressionContext *context, QString &errorMessage SIP_OUT );

    void setExpression( const QString &expression );

    QString expression() const;

    QString dump() const;

    QgsDistanceArea *geomCalculator();

    void setGeomCalculator( const QgsDistanceArea *calc );

    Qgis::DistanceUnit distanceUnits() const;

    void setDistanceUnits( Qgis::DistanceUnit unit );

    Qgis::AreaUnit areaUnits() const;

    void setAreaUnits( Qgis::AreaUnit unit );

    static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context, const QgsDistanceArea *distanceArea = nullptr );

    static QSet<QString> referencedVariables( const QString &text );
 
    // TODO QGIS 5.0 -- remove this function in favour of version with explicit context
    Q_DECL_DEPRECATED static double evaluateToDouble( const QString &text, double fallbackValue ) SIP_DEPRECATED;

    static double evaluateToDouble( const QString &text, double fallbackValue, const QgsExpressionContext *context );
 
    enum SpatialOperator
    {
      soBbox,
      soIntersects,
      soContains,
      soCrosses,
      soEquals,
      soDisjoint,
      soOverlaps,
      soTouches,
      soWithin,
    };

    SIP_SKIP static const FunctionListSnapshot getFunctionsSnapshot();
 
    // NOTE tagged as deprecated as we don't want this used from c++ code
    Q_DECL_DEPRECATED static QList<QgsExpressionFunction *> Functions();

    static QStringList BuiltinFunctions();

    static bool registerFunction( QgsExpressionFunction *function, bool transferOwnership = false );

    static bool unregisterFunction( const QString &name );

    static void cleanRegisteredFunctions();

    static bool isFunctionName( const QString &name );
 
    // NOTE tagged as deprecated as we don't want this used from c++ code
    Q_DECL_DEPRECATED static int functionIndex( const QString &name );

    static int functionCount();

    static QString quotedColumnRef( QString name );

    static QString quotedString( QString text );

    static QString quotedValue( const QVariant &value );

    static QString quotedValue( const QVariant &value, QMetaType::Type type );

    Q_DECL_DEPRECATED static QString quotedValue( const QVariant &value, QVariant::Type type ) SIP_DEPRECATED;

 
#ifndef SIP_RUN
    static HelpTextHash &functionHelpTexts();
#endif

    static QString helpText( QString name );

    static QStringList tags( const QString &name );

    static bool addVariableHelpText( const QString name, const QString &description );

    static QString variableHelpText( const QString &variableName );

    static QString formatVariableHelp( const QString &description, bool showValue = true, const QVariant &value = QVariant() );

    static QString group( const QString &group );

    static QString formatPreviewString( const QVariant &value, bool htmlOutput = true, int maximumPreviewLength = 60 );

    static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value, QMetaType::Type fieldType = QMetaType::Type::UnknownType );

    Q_DECL_DEPRECATED static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value, QVariant::Type fieldType ) SIP_DEPRECATED;

    static bool isFieldEqualityExpression( const QString &expression, QString &field SIP_OUT, QVariant &value SIP_OUT );

    static bool attemptReduceToInClause( const QStringList &expressions, QString &result SIP_OUT );

    QgsExpression simplified() const;
 
    // clang-format off
#ifdef SIP_RUN
    SIP_PYOBJECT __repr__();
    % MethodCode
    QString str = u"<QgsExpression: '%1'>"_s.arg( sipCpp->expression() );
    sipRes = PyUnicode_FromString( str.toUtf8().constData() );
  % End
#endif
 
  private:
    // clang-format on
 
    void initGeomCalculator( const QgsExpressionContext *context );

    void detach() SIP_SKIP;
 
    QgsExpressionPrivate *d = nullptr;
 
    static HelpTextHash sFunctionHelpTexts;

    static void initFunctionHelp() SIP_SKIP;
    static void buildFunctionHelp() SIP_SKIP;
    static void initVariableHelp() SIP_SKIP;
    static void buildVariableHelp() SIP_SKIP;
 
    friend class QgsExpressionNodeFunction;
 
#if defined( __clang__ )
    static AtomicSharedPtr<FunctionListSnapshot> sFunctions;
#else
    static std::atomic<FunctionListSnapshot> sFunctions;
#endif
    static QMutex sFunctionWriteMutex;
 
    static QStringList sBuiltinFunctionNames;
 
    friend class QgsOgcUtils;
};
 
Q_DECLARE_METATYPE( QgsExpression )
 
#endif // QGSEXPRESSION_H