qgsexpressionfunction.h

Go to the documentation of this file.

/***************************************************************************
                               qgsexpressionfunction.h
                             -------------------
    begin                : May 2017
    copyright            : (C) 2017 Matthias Kuhn
    email                : matthias@opengis.ch
 ***************************************************************************
 *                                                                         *
 *   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 QGSEXPRESSIONFUNCTION_H
#define QGSEXPRESSIONFUNCTION_H
 
#include <functional>
 
#include "qgis.h"
#include "qgis_core.h"
#include "qgsexpressionnode.h"
 
#include <QJsonDocument>
#include <QJsonObject>
#include <QMutex>
#include <QSet>
#include <QString>
#include <QVariant>
 
class QgsExpressionNodeFunction;
class QgsExpression;
class QgsExpressionContext;
class QgsExpressionContextScope;

class CORE_EXPORT QgsExpressionFunction
{
  public:
    typedef QVariant ( *FcnEval )( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) SIP_SKIP;

    class CORE_EXPORT Parameter
    {
      public:
        Parameter( const QString &name, bool optional = false, const QVariant &defaultValue = QVariant(), bool isSubExpression = false )
          : mName( name )
          , mOptional( optional )
          , mDefaultValue( defaultValue )
          , mIsSubExpression( isSubExpression )
        {}

        QString name() const { return mName; }

        bool optional() const { return mOptional; }

        QVariant defaultValue() const { return mDefaultValue; }

        bool isSubExpression() const { return mIsSubExpression; }
 
        bool operator==( const QgsExpressionFunction::Parameter &other ) const { return ( QString::compare( mName, other.mName, Qt::CaseInsensitive ) == 0 ); }
 
      private:
        QString mName;
        bool mOptional = false;
        QVariant mDefaultValue;
        bool mIsSubExpression = false;
    };

    typedef QList< QgsExpressionFunction::Parameter > ParameterList;

    QgsExpressionFunction( const QString &fnname, int params, const QString &group, const QString &helpText = QString(), bool lazyEval = false, bool handlesNull = false, bool isContextual = false )
      : mName( fnname )
      , mParams( params )
      , mGroups( group.isEmpty() ? QStringList() : QStringList() << group )
      , mHelpText( helpText )
      , mLazyEval( lazyEval )
      , mHandlesNull( handlesNull )
      , mIsContextual( isContextual )
    {}

    QgsExpressionFunction( const QString &fnname, int params, const QStringList &groups, const QString &helpText = QString(), bool lazyEval = false, bool handlesNull = false, bool isContextual = false )
      : mName( fnname )
      , mParams( params )
      , mGroups( groups )
      , mHelpText( helpText )
      , mLazyEval( lazyEval )
      , mHandlesNull( handlesNull )
      , mIsContextual( isContextual )
    {}

    QgsExpressionFunction(
      const QString &fnname,
      const QgsExpressionFunction::ParameterList &params,
      const QString &group,
      const QString &helpText = QString(),
      bool lazyEval = false,
      bool handlesNull = false,
      bool isContextual = false
    )
      : mName( fnname )
      , mParams( 0 )
      , mParameterList( params )
      , mGroups( group.isEmpty() ? QStringList() : QStringList() << group )
      , mHelpText( helpText )
      , mLazyEval( lazyEval )
      , mHandlesNull( handlesNull )
      , mIsContextual( isContextual )
    {}

    QgsExpressionFunction(
      const QString &fnname,
      const QgsExpressionFunction::ParameterList &params,
      const QStringList &groups,
      const QString &helpText = QString(),
      bool lazyEval = false,
      bool handlesNull = false,
      bool isContextual = false
    )
      : mName( fnname )
      , mParams( 0 )
      , mParameterList( params )
      , mGroups( groups )
      , mHelpText( helpText )
      , mLazyEval( lazyEval )
      , mHandlesNull( handlesNull )
      , mIsContextual( isContextual )
    {}
 
    virtual ~QgsExpressionFunction() = default;

    QString name() const { return mName; }

    int params() const { return mParameterList.isEmpty() ? mParams : mParameterList.count(); }

    int minParams() const
    {
      if ( mParameterList.isEmpty() )
        return mParams;
 
      int min = 0;
      for ( const Parameter &param : mParameterList )
      {
        if ( !param.optional() )
          min++;
      }
      return min;
    }

    const QgsExpressionFunction::ParameterList &parameters() const { return mParameterList; }

    virtual bool usesGeometry( const QgsExpressionNodeFunction *node ) const;

    virtual QStringList aliases() const;

    bool lazyEval() const { return mLazyEval; }

    virtual bool isStatic( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const;

    virtual bool prepare( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const;

    virtual QSet<QString> referencedColumns( const QgsExpressionNodeFunction *node ) const;

    bool isContextual() const { return mIsContextual; }

    virtual bool isDeprecated() const;

    QString group() const { return mGroups.isEmpty() ? QString() : mGroups.at( 0 ); }

    QStringList groups() const { return mGroups; }

    const QString helpText() const;

    virtual QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) = 0;

    virtual QVariant run( QgsExpressionNode::NodeList *args, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node );
 
    bool operator==( const QgsExpressionFunction &other ) const;

    virtual bool handlesNull() const;
 
  protected:
    static bool allParamsStatic( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context );
 
  private:
    QString mName;
    int mParams;
    QgsExpressionFunction::ParameterList mParameterList;
    QStringList mGroups;
    QString mHelpText;
    bool mLazyEval;
    bool mHandlesNull;
    bool mIsContextual; //if true function is only available through an expression context
};

#ifndef SIP_RUN
class QgsStaticExpressionFunction : public QgsExpressionFunction
{
  public:
    QgsStaticExpressionFunction(
      const QString &fnname,
      int params,
      FcnEval fcn,
      const QString &group,
      const QString &helpText = QString(),
      bool usesGeometry = false,
      const QSet<QString> &referencedColumns = QSet<QString>(),
      bool lazyEval = false,
      const QStringList &aliases = QStringList(),
      bool handlesNull = false
    )
      : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull )
      , mFnc( fcn )
      , mAliases( aliases )
      , mUsesGeometry( usesGeometry )
      , mReferencedColumns( referencedColumns )
    {}

    QgsStaticExpressionFunction(
      const QString &fnname,
      int params,
      FcnEval fcn,
      const QStringList &groups,
      const QString &helpText = QString(),
      bool usesGeometry = false,
      const QSet<QString> &referencedColumns = QSet<QString>(),
      bool lazyEval = false,
      const QStringList &aliases = QStringList(),
      bool handlesNull = false
    )
      : QgsExpressionFunction( fnname, params, groups, helpText, lazyEval, handlesNull )
      , mFnc( fcn )
      , mAliases( aliases )
      , mUsesGeometry( usesGeometry )
      , mReferencedColumns( referencedColumns )
    {}

    QgsStaticExpressionFunction(
      const QString &fnname,
      const QgsExpressionFunction::ParameterList &params,
      FcnEval fcn,
      const QString &group,
      const QString &helpText = QString(),
      bool usesGeometry = false,
      const QSet<QString> &referencedColumns = QSet<QString>(),
      bool lazyEval = false,
      const QStringList &aliases = QStringList(),
      bool handlesNull = false
    )
      : QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull )
      , mFnc( fcn )
      , mAliases( aliases )
      , mUsesGeometry( usesGeometry )
      , mReferencedColumns( referencedColumns )
    {}

    QgsStaticExpressionFunction(
      const QString &fnname,
      const QgsExpressionFunction::ParameterList &params,
      FcnEval fcn,
      const QString &group,
      const QString &helpText,
      const std::function< bool( const QgsExpressionNodeFunction *node )> &usesGeometry,
      const std::function< QSet<QString>( const QgsExpressionNodeFunction *node )> &referencedColumns,
      bool lazyEval = false,
      const QStringList &aliases = QStringList(),
      bool handlesNull = false
    );

    QgsStaticExpressionFunction(
      const QString &fnname,
      const QgsExpressionFunction::ParameterList &params,
      FcnEval fcn,
      const QStringList &groups,
      const QString &helpText = QString(),
      bool usesGeometry = false,
      const QSet<QString> &referencedColumns = QSet<QString>(),
      bool lazyEval = false,
      const QStringList &aliases = QStringList(),
      bool handlesNull = false
    )
      : QgsExpressionFunction( fnname, params, groups, helpText, lazyEval, handlesNull )
      , mFnc( fcn )
      , mAliases( aliases )
      , mUsesGeometry( usesGeometry )
      , mReferencedColumns( referencedColumns )
    {}

    QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override
    {
      return mFnc ? mFnc( values, context, parent, node ) : QVariant();
    }
 
    QStringList aliases() const override;
 
    bool usesGeometry( const QgsExpressionNodeFunction *node ) const override;

    void setUsesGeometryFunction( const std::function< bool( const QgsExpressionNodeFunction *node )> &usesGeometry );
 
    QSet<QString> referencedColumns( const QgsExpressionNodeFunction *node ) const override;
 
    bool isStatic( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const override;
 
    bool prepare( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const override;

    void setIsStaticFunction( const std::function< bool( const QgsExpressionNodeFunction *, QgsExpression *, const QgsExpressionContext * ) > &isStatic );
 

    void setIsStatic( bool isStatic );

    void setPrepareFunction( const std::function< bool( const QgsExpressionNodeFunction *, QgsExpression *, const QgsExpressionContext * )> &prepareFunc );

    static const QList<QgsExpressionFunction *> &functions();
 
  private:
    FcnEval mFnc;
    QStringList mAliases;
    bool mUsesGeometry;
    std::function< bool( const QgsExpressionNodeFunction *node ) > mUsesGeometryFunc;
    std::function< QSet<QString>( const QgsExpressionNodeFunction *node ) > mReferencedColumnsFunc;
    std::function< bool( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) > mIsStaticFunc = allParamsStatic;
    std::function< bool( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) > mPrepareFunc;
    QSet<QString> mReferencedColumns;
    bool mIsStatic = false;
};

class QgsArrayForeachExpressionFunction : public QgsExpressionFunction
{
  public:
    QgsArrayForeachExpressionFunction();
 
    bool isStatic( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const override;
 
    QVariant run( QgsExpressionNode::NodeList *args, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override;
 
    QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override;
 
    bool prepare( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const override;
};

class QgsArrayFilterExpressionFunction : public QgsExpressionFunction
{
  public:
    QgsArrayFilterExpressionFunction();
 
    bool isStatic( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const override;
 
    QVariant run( QgsExpressionNode::NodeList *args, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override;
 
    QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override;
 
    bool prepare( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const override;
};

class QgsWithVariableExpressionFunction : public QgsExpressionFunction
{
  public:
    QgsWithVariableExpressionFunction();
 
    bool isStatic( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const override;
 
    QVariant run( QgsExpressionNode::NodeList *args, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override;
 
    QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) override;
 
    bool prepare( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const override;
 
  private:
    void appendTemporaryVariable( const QgsExpressionContext *context, const QString &name, const QVariant &value ) const;

    void popTemporaryVariable( const QgsExpressionContext *context ) const;
};
 
#endif
 
#endif // QGSEXPRESSIONFUNCTION_H