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


    static QString helpText( QString name );

    static QStringList tags( const 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 );

    void detach() SIP_SKIP;

    QgsExpressionPrivate *d = nullptr;

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

    friend class QgsOgcUtils;
};

Q_DECLARE_METATYPE( QgsExpression )

#endif // QGSEXPRESSION_H