QGIS API Documentation 3.37.0-Master (fdefdf9c27f)
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
35class QgsFeature;
36class QgsGeometry;
37class QgsOgcUtils;
38class QgsVectorLayer;
40class QgsField;
41class QgsFields;
42class QgsDistanceArea;
43class QDomElement;
45class QgsExpressionPrivate;
47
48#ifndef SIP_RUN
50struct 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
70struct 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
84struct 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
111struct 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
129typedef QHash<QString, Help> HelpTextHash;
130
132#endif
133
189class 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
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:4124
AreaUnit
Units of area.
Definition: qgis.h:4162
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.