QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
qgsexpression.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgsexpression.h
3  -------------------
4  begin : August 2011
5  copyright : (C) 2011 Martin Dobias
6  email : wonder.sk at gmail dot com
7  ***************************************************************************
8  * *
9  * This program is free software; you can redistribute it and/or modify *
10  * it under the terms of the GNU General Public License as published by *
11  * the Free Software Foundation; either version 2 of the License, or *
12  * (at your option) any later version. *
13  * *
14  ***************************************************************************/
15 
16 #ifndef QGSEXPRESSION_H
17 #define QGSEXPRESSION_H
18 
19 #include "qgis_core.h"
20 #include <QMetaType>
21 #include <QStringList>
22 #include <QVariant>
23 #include <QList>
24 #include <QDomDocument>
25 #include <QCoreApplication>
26 #include <QSet>
27 #include <QRecursiveMutex>
28 
29 #include <functional>
30 
31 #include "qgis.h"
32 #include "qgsinterval.h"
33 #include "qgsexpressionnode.h"
34 
35 class QgsFeature;
36 class QgsGeometry;
37 class QgsOgcUtils;
38 class QgsVectorLayer;
40 class QgsField;
41 class QgsFields;
42 class QgsDistanceArea;
43 class QDomElement;
45 class QgsExpressionPrivate;
47 
48 #ifndef SIP_RUN
50 struct HelpArg
51 {
52  HelpArg( const QString &arg, const QString &desc, bool descOnly = false, bool syntaxOnly = false,
53  bool optional = false, const QString &defaultVal = QString() )
54  : mArg( arg )
55  , mDescription( desc )
56  , mDescOnly( descOnly )
57  , mSyntaxOnly( syntaxOnly )
58  , mOptional( optional )
59  , mDefaultVal( defaultVal )
60  {}
61 
62  QString mArg;
63  QString mDescription;
64  bool mDescOnly;
65  bool mSyntaxOnly;
66  bool mOptional;
67  QString mDefaultVal;
68 };
69 
70 struct HelpExample
71 {
72  HelpExample( const QString &expression, const QString &returns, const QString &note = QString() )
73  : mExpression( expression )
74  , mReturns( returns )
75  , mNote( note )
76  {}
77 
78  QString mExpression;
79  QString mReturns;
80  QString mNote;
81 };
82 
83 
84 struct HelpVariant
85 {
86  HelpVariant( const QString &name, const QString &description,
87  const QList<HelpArg> &arguments = QList<HelpArg>(),
88  bool variableLenArguments = false,
89  const QList<HelpExample> &examples = QList<HelpExample>(),
90  const QString &notes = QString(),
91  const QStringList &tags = QStringList() )
92  : mName( name )
93  , mDescription( description )
94  , mArguments( arguments )
95  , mVariableLenArguments( variableLenArguments )
96  , mExamples( examples )
97  , mNotes( notes )
98  , mTags( tags )
99  {}
100 
101  QString mName;
102  QString mDescription;
103  QList<HelpArg> mArguments;
104  bool mVariableLenArguments;
105  QList<HelpExample> mExamples;
106  QString mNotes;
107  QStringList mTags;
108 };
109 
110 
111 struct Help
112 {
114  Help() = default;
115 
116  Help( const QString &name, const QString &type, const QString &description, const QList<HelpVariant> &variants )
117  : mName( name )
118  , mType( type )
119  , mDescription( description )
120  , mVariants( variants )
121  {}
122 
123  QString mName;
124  QString mType;
125  QString mDescription;
126  QList<HelpVariant> mVariants;
127 };
128 
129 typedef QHash<QString, Help> HelpTextHash;
130 
132 #endif
133 
189 class CORE_EXPORT QgsExpression
190 {
191  Q_DECLARE_TR_FUNCTIONS( QgsExpression )
192  public:
193 
197  struct CORE_EXPORT ParserError
198  {
200  {
201  Unknown = 0,
202  FunctionUnknown = 1,
203  FunctionWrongArgs = 2,
204  FunctionInvalidParams = 3,
205  FunctionNamedArgsError = 4
206  };
207 
211  ParserErrorType errorType = ParserErrorType::Unknown;
212 
216  QString errorMsg;
217 
222  int firstLine = 0;
223 
228  int firstColumn = 0;
229 
233  int lastLine = 0;
234 
238  int lastColumn = 0;
239  };
240 
247  QgsExpression( const QString &expr );
248 
254  QgsExpression( const QgsExpression &other );
255 
261  QgsExpression &operator=( const QgsExpression &other );
262 
267  operator QString() const SIP_SKIP;
268 
273  QgsExpression();
274 
275  ~QgsExpression();
276 
282  bool operator==( const QgsExpression &other ) const;
283 
289  bool isValid() const;
290 
292  bool hasParserError() const;
294  QString parserErrorString() const;
295 
299  QList<QgsExpression::ParserError> parserErrors() const;
300 
306  const QgsExpressionNode *rootNode() const;
307 
312  bool prepare( const QgsExpressionContext *context );
313 
331  QSet<QString> referencedColumns() const;
332 
343  QSet<QString> referencedVariables() const;
344 
354  QSet<QString> referencedFunctions() const;
355 
356 #ifndef SIP_RUN
357 
364  QList<const QgsExpressionNode *> nodes( ) const;
365 
372  template <class T>
373  QList<const T *> findNodes( ) const
374  {
375  QList<const T *> lst;
376  const QList<const QgsExpressionNode *> allNodes( nodes() );
377  for ( const auto &node : allNodes )
378  {
379  const T *n = dynamic_cast<const T *>( node );
380  if ( n )
381  lst << n;
382  }
383  return lst;
384  }
385 #endif
386 
399  QSet<int> referencedAttributeIndexes( const QgsFields &fields ) const;
400 
402  bool needsGeometry() const;
403 
404  // evaluation
405 
410  QVariant evaluate();
411 
417  QVariant evaluate( const QgsExpressionContext *context );
418 
420  bool hasEvalError() const;
422  QString evalErrorString() const;
424  void setEvalErrorString( const QString &str );
425 
431  bool isField() const;
432 
445  static int expressionToLayerFieldIndex( const QString &expression, const QgsVectorLayer *layer );
446 
459  static QString quoteFieldExpression( const QString &expression, const QgsVectorLayer *layer );
460 
468  static bool checkExpression( const QString &text, const QgsExpressionContext *context, QString &errorMessage SIP_OUT );
469 
474  void setExpression( const QString &expression );
475 
481  QString expression() const;
482 
489  QString dump() const;
490 
498  QgsDistanceArea *geomCalculator();
499 
513  void setGeomCalculator( const QgsDistanceArea *calc );
514 
521  Qgis::DistanceUnit distanceUnits() const;
522 
531  void setDistanceUnits( Qgis::DistanceUnit unit );
532 
539  Qgis::AreaUnit areaUnits() const;
540 
549  void setAreaUnits( Qgis::AreaUnit unit );
550 
561  static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context,
562  const QgsDistanceArea *distanceArea = nullptr );
563 
571  static QSet<QString> referencedVariables( const QString &text );
572 
582  static double evaluateToDouble( const QString &text, double fallbackValue );
583 
585  {
595  };
596 
597  static const QList<QgsExpressionFunction *> &Functions();
598 
599  static const QStringList &BuiltinFunctions();
600 
608  static bool registerFunction( QgsExpressionFunction *function, bool transferOwnership = false );
609 
615  static bool unregisterFunction( const QString &name );
616 
620  static void cleanRegisteredFunctions();
621 
623  static bool isFunctionName( const QString &name );
624 
626  static int functionIndex( const QString &name );
627 
632  static int functionCount();
633 
639  static QString quotedColumnRef( QString name );
640 
646  static QString quotedString( QString text );
647 
655  static QString quotedValue( const QVariant &value );
656 
665  static QString quotedValue( const QVariant &value, QVariant::Type type );
666 
668 
669 #ifndef SIP_RUN
671  static HelpTextHash &functionHelpTexts();
673 #endif
674 
681  static QString helpText( QString name );
682 
688  static QStringList tags( const QString &name );
689 
702  static bool addVariableHelpText( const QString name, const QString &description );
703 
710  static QString variableHelpText( const QString &variableName );
711 
720  static QString formatVariableHelp( const QString &description, bool showValue = true, const QVariant &value = QVariant() );
721 
726  static QString group( const QString &group );
727 
736  static QString formatPreviewString( const QVariant &value, bool htmlOutput = true, int maximumPreviewLength = 60 );
737 
746  static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value, QVariant::Type fieldType = QVariant::Type::Invalid );
747 
758  static bool isFieldEqualityExpression( const QString &expression, QString &field SIP_OUT, QVariant &value SIP_OUT );
759 
774  static bool attemptReduceToInClause( const QStringList &expressions, QString &result SIP_OUT );
775 
776 #ifdef SIP_RUN
777  SIP_PYOBJECT __repr__();
778  % MethodCode
779  QString str = QStringLiteral( "<QgsExpression: '%1'>" ).arg( sipCpp->expression() );
780  sipRes = PyUnicode_FromString( str.toUtf8().constData() );
781  % End
782 #endif
783 
784  private:
785  void initGeomCalculator( const QgsExpressionContext *context );
786 
793  void detach() SIP_SKIP;
794 
795  QgsExpressionPrivate *d = nullptr;
796 
797  static HelpTextHash sFunctionHelpTexts;
798 
800  static void initFunctionHelp() SIP_SKIP;
802  static void initVariableHelp() SIP_SKIP;
803 
805  static QRecursiveMutex sFunctionsMutex;
806  static QMap< QString, int> sFunctionIndexMap;
807 
808  friend class QgsOgcUtils;
809 };
810 
812 
813 #endif // QGSEXPRESSION_H
DistanceUnit
Units of distance.
Definition: qgis.h:4090
AreaUnit
Units of area.
Definition: qgis.h:4128
A general purpose distance and area calculator, capable of performing ellipsoid based calculations.
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
A abstract base class for defining QgsExpression functions.
An expression node for expression functions.
Abstract base class for all nodes that can appear in an expression.
Class for parsing and evaluation of expressions (formerly called "search strings").
QList< const T * > findNodes() const
Returns a list of all nodes of the given class which are used in this expression.
The feature class encapsulates a single feature including its unique ID, geometry and a list of field...
Definition: qgsfeature.h:56
Encapsulate a field in an attribute table or data source.
Definition: qgsfield.h:53
Container of fields for a vector layer.
Definition: qgsfields.h:45
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:162
The QgsOgcUtils class provides various utility functions for conversion between OGC (Open Geospatial ...
Definition: qgsogcutils.h:54
This is the base class for vector data providers.
Represents a vector layer which manages a vector based data sets.
#define str(x)
Definition: qgis.cpp:38
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_OUT
Definition: qgis_sip.h:58
Q_DECLARE_METATYPE(QgsDatabaseQueryLogEntry)
QString formatVariableHelp(const QString &variable, const QString &description, bool showValue, const QVariant &value)
Returns a HTML formatted string for use as a variable item help.
Details about any parser errors that were found when parsing the expression.
QString errorMsg
The message for the error at this location.