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 "qgis_core.h"
#include <QMetaType>
#include <QStringList>
#include <QVariant>
#include <QList>
#include <QDomDocument>
#include <QCoreApplication>
#include <QSet>
#include <functional>

#include "qgis.h"
#include "qgsunittypes.h"
#include "qgsinterval.h"
#include "qgsexpressionnode.h"

class QgsFeature;
class QgsGeometry;
class QgsOgcUtils;
class QgsVectorLayer;
class QgsVectorDataProvider;
class QgsField;
class QgsFields;
class QgsDistanceArea;
class QDomElement;
class QgsExpressionContext;
class QgsExpressionPrivate;
class QgsExpressionFunction;

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

      ParserErrorType errorType = 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 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 );

    QgsUnitTypes::DistanceUnit distanceUnits() const;

    void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );

    QgsUnitTypes::AreaUnit areaUnits() const;

    void setAreaUnits( QgsUnitTypes::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 QList<QgsExpressionFunction *> sFunctions SIP_SKIP;
    static const QList<QgsExpressionFunction *> &Functions();

    static QStringList sBuiltinFunctions SIP_SKIP;
    static const QStringList &BuiltinFunctions();

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

    static bool unregisterFunction( const QString &name );

    static QList<QgsExpressionFunction *> sOwnedFunctions SIP_SKIP;

    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, QVariant::Type type );


    static QString helpText( QString name );

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

    static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value );

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

    struct HelpArg SIP_SKIP
    {
      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 SIP_SKIP
    {
      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 SIP_SKIP
    {
      HelpVariant( const QString &name, const QString &description,
                   const QList<QgsExpression::HelpArg> &arguments = QList<QgsExpression::HelpArg>(),
                   bool variableLenArguments = false,
                   const QList<QgsExpression::HelpExample> &examples = QList<QgsExpression::HelpExample>(),
                   const QString &notes = QString() )
        : mName( name )
        , mDescription( description )
        , mArguments( arguments )
        , mVariableLenArguments( variableLenArguments )
        , mExamples( examples )
        , mNotes( notes )
      {}

      QString mName;
      QString mDescription;
      QList<QgsExpression::HelpArg> mArguments;
      bool mVariableLenArguments;
      QList<QgsExpression::HelpExample> mExamples;
      QString mNotes;
    };

    struct Help SIP_SKIP
    {
      Help() = default;

      Help( const QString &name, const QString &type, const QString &description, const QList<QgsExpression::HelpVariant> &variants )
        : mName( name )
        , mType( type )
        , mDescription( description )
        , mVariants( variants )
      {}

      QString mName;
      QString mType;
      QString mDescription;
      QList<QgsExpression::HelpVariant> mVariants;
    };

    void detach() SIP_SKIP;

    QgsExpressionPrivate *d = nullptr;

    static QHash<QString, Help> sFunctionHelpTexts;
    static QHash<QString, QString> sVariableHelpTexts;
    static QHash<QString, QString> sGroups;

    static void initFunctionHelp() SIP_SKIP;
    static void initVariableHelp() SIP_SKIP;

    friend class QgsOgcUtils;
};

Q_DECLARE_METATYPE( QgsExpression )

#endif // QGSEXPRESSION_H