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 <QString>
#include <QVariant>
#include <QSet>
#include <QJsonDocument>
#include <QJsonObject>
 
#include "qgis.h"
#include "qgis_core.h"
#include "qgsexpressionnode.h"
 
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