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 <QCoreApplication>
#include <QDomDocument>
#include <QList>
#include <QMetaType>
#include <QRecursiveMutex>
#include <QSet>
#include <QStringList>
#include <QVariant>
 
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:

    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 );

    static double evaluateToDouble( const QString &text, double fallbackValue );
 
    enum SpatialOperator
    {
      soBbox,
      soIntersects,
      soContains,
      soCrosses,
      soEquals,
      soDisjoint,
      soOverlaps,
      soTouches,
      soWithin,
    };
 
    static const QList<QgsExpressionFunction *> &Functions();
 
    static const 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 );

    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 );
 
#ifdef SIP_RUN
    SIP_PYOBJECT __repr__();
    % MethodCode
    QString str = QStringLiteral( "<QgsExpression: '%1'>" ).arg( sipCpp->expression() );
    sipRes = PyUnicode_FromString( str.toUtf8().constData() );
    % End
#endif
 
  private:
    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;
    static QRecursiveMutex sFunctionsMutex;
    static QMap< QString, int> sFunctionIndexMap;
 
    friend class QgsOgcUtils;
};
 
Q_DECLARE_METATYPE( QgsExpression )
 
#endif // QGSEXPRESSION_H