QGIS API Documentation  3.3.0-Master (208571a)
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 <functional>
28 
29 #include "qgis.h"
30 #include "qgsunittypes.h"
31 #include "qgsinterval.h"
32 #include "qgsexpressionnode.h"
33 
34 class QgsFeature;
35 class QgsGeometry;
36 class QgsOgcUtils;
37 class QgsVectorLayer;
39 class QgsField;
40 class QgsFields;
41 class QgsDistanceArea;
42 class QDomElement;
44 class QgsExpressionPrivate;
46 
113 class CORE_EXPORT QgsExpression
114 {
115  Q_DECLARE_TR_FUNCTIONS( QgsExpression )
116  public:
117 
122  struct CORE_EXPORT ParserError
123  {
125  {
126  Unknown = 0,
127  FunctionUnknown = 1,
128  FunctionWrongArgs = 2,
129  FunctionInvalidParams = 3,
130  FunctionNamedArgsError = 4
131  };
132 
136  ParserErrorType errorType = ParserErrorType::Unknown;
137 
141  QString errorMsg;
142 
147  int firstLine = 0;
148 
153  int firstColumn = 0;
154 
158  int lastLine = 0;
159 
163  int lastColumn = 0;
164  };
165 
172  QgsExpression( const QString &expr );
173 
179  QgsExpression( const QgsExpression &other );
180 
186  QgsExpression &operator=( const QgsExpression &other );
187 
193  operator QString() const SIP_SKIP;
194 
200  QgsExpression();
201 
202  ~QgsExpression();
203 
210  bool operator==( const QgsExpression &other ) const;
211 
218  bool isValid() const;
219 
221  bool hasParserError() const;
223  QString parserErrorString() const;
224 
229  QList<QgsExpression::ParserError> parserErrors() const;
230 
232  const QgsExpressionNode *rootNode() const;
233 
239  bool prepare( const QgsExpressionContext *context );
240 
250  QSet<QString> referencedColumns() const;
251 
259  QSet<QString> referencedVariables() const;
260 
266  QSet<QString> referencedFunctions() const;
267 
268 #ifndef SIP_RUN
269 
276  QList<const QgsExpressionNode *> nodes( ) const;
277 
284  template <class T>
285  QList<const T *> findNodes( ) const
286  {
287  QList<const T *> lst;
288  const QList<const QgsExpressionNode *> allNodes( nodes() );
289  for ( const auto &node : allNodes )
290  {
291  const T *n = dynamic_cast<const T *>( node );
292  if ( n )
293  lst << n;
294  }
295  return lst;
296  }
297 #endif
298 
304  QSet<int> referencedAttributeIndexes( const QgsFields &fields ) const;
305 
307  bool needsGeometry() const;
308 
309  // evaluation
310 
316  QVariant evaluate();
317 
324  QVariant evaluate( const QgsExpressionContext *context );
325 
327  bool hasEvalError() const;
329  QString evalErrorString() const;
331  void setEvalErrorString( const QString &str );
332 
337  bool isField() const;
338 
347  static bool checkExpression( const QString &text, const QgsExpressionContext *context, QString &errorMessage SIP_OUT );
348 
354  void setExpression( const QString &expression );
355 
361  QString expression() const;
362 
369  QString dump() const;
370 
378  QgsDistanceArea *geomCalculator();
379 
389  void setGeomCalculator( const QgsDistanceArea *calc );
390 
398  QgsUnitTypes::DistanceUnit distanceUnits() const;
399 
407  void setDistanceUnits( QgsUnitTypes::DistanceUnit unit );
408 
416  QgsUnitTypes::AreaUnit areaUnits() const;
417 
425  void setAreaUnits( QgsUnitTypes::AreaUnit unit );
426 
438  static QString replaceExpressionText( const QString &action, const QgsExpressionContext *context,
439  const QgsDistanceArea *distanceArea = nullptr );
440 
448  static QSet<QString> referencedVariables( const QString &text );
449 
460  static double evaluateToDouble( const QString &text, double fallbackValue );
461 
463  {
473  };
474 
476  static QList<QgsExpressionFunction *> sFunctions SIP_SKIP;
477  static const QList<QgsExpressionFunction *> &Functions();
478 
480  static QStringList sBuiltinFunctions SIP_SKIP;
481  static const QStringList &BuiltinFunctions();
482 
490  static bool registerFunction( QgsExpressionFunction *function, bool transferOwnership = false );
491 
497  static bool unregisterFunction( const QString &name );
498 
503  static QList<QgsExpressionFunction *> sOwnedFunctions SIP_SKIP;
504 
509  static void cleanRegisteredFunctions();
510 
512  static bool isFunctionName( const QString &name );
513 
515  static int functionIndex( const QString &name );
516 
521  static int functionCount();
522 
528  static QString quotedColumnRef( QString name );
529 
535  static QString quotedString( QString text );
536 
545  static QString quotedValue( const QVariant &value );
546 
556  static QString quotedValue( const QVariant &value, QVariant::Type type );
557 
559 
566  static QString helpText( QString name );
567 
574  static QString variableHelpText( const QString &variableName );
575 
585  static QString formatVariableHelp( const QString &description, bool showValue = true, const QVariant &value = QVariant() );
586 
591  static QString group( const QString &group );
592 
601  static QString formatPreviewString( const QVariant &value, bool htmlOutput = true );
602 
611  static QString createFieldEqualityExpression( const QString &fieldName, const QVariant &value );
612 
613 #ifdef SIP_RUN
614  SIP_PYOBJECT __repr__();
615  % MethodCode
616  QString str = QStringLiteral( "<QgsExpression: '%1'>" ).arg( sipCpp->expression() );
617  sipRes = PyUnicode_FromString( str.toUtf8().data() );
618  % End
619 #endif
620 
621  private:
622  void initGeomCalculator();
623 
624  struct HelpArg SIP_SKIP
625  {
626  HelpArg( const QString &arg, const QString &desc, bool descOnly = false, bool syntaxOnly = false,
627  bool optional = false, const QString &defaultVal = QString() )
628  : mArg( arg )
629  , mDescription( desc )
630  , mDescOnly( descOnly )
631  , mSyntaxOnly( syntaxOnly )
632  , mOptional( optional )
633  , mDefaultVal( defaultVal )
634  {}
635 
636  QString mArg;
637  QString mDescription;
638  bool mDescOnly;
639  bool mSyntaxOnly;
640  bool mOptional;
641  QString mDefaultVal;
642  };
643 
644  struct HelpExample SIP_SKIP
645  {
646  HelpExample( const QString &expression, const QString &returns, const QString &note = QString() )
647  : mExpression( expression )
648  , mReturns( returns )
649  , mNote( note )
650  {}
651 
652  QString mExpression;
653  QString mReturns;
654  QString mNote;
655  };
656 
657  struct HelpVariant SIP_SKIP
658  {
659  HelpVariant( const QString &name, const QString &description,
660  const QList<QgsExpression::HelpArg> &arguments = QList<QgsExpression::HelpArg>(),
661  bool variableLenArguments = false,
662  const QList<QgsExpression::HelpExample> &examples = QList<QgsExpression::HelpExample>(),
663  const QString &notes = QString() )
664  : mName( name )
665  , mDescription( description )
666  , mArguments( arguments )
667  , mVariableLenArguments( variableLenArguments )
668  , mExamples( examples )
669  , mNotes( notes )
670  {}
671 
672  QString mName;
673  QString mDescription;
674  QList<QgsExpression::HelpArg> mArguments;
675  bool mVariableLenArguments;
676  QList<QgsExpression::HelpExample> mExamples;
677  QString mNotes;
678  };
679 
680  struct Help SIP_SKIP
681  {
683  Help() = default;
684 
685  Help( const QString &name, const QString &type, const QString &description, const QList<QgsExpression::HelpVariant> &variants )
686  : mName( name )
687  , mType( type )
688  , mDescription( description )
689  , mVariants( variants )
690  {}
691 
692  QString mName;
693  QString mType;
694  QString mDescription;
695  QList<QgsExpression::HelpVariant> mVariants;
696  };
697 
704  void detach() SIP_SKIP;
705 
706  QgsExpressionPrivate *d = nullptr;
707 
708  static QHash<QString, Help> sFunctionHelpTexts;
709  static QHash<QString, QString> sVariableHelpTexts;
710  static QHash<QString, QString> sGroups;
711 
713  static void initFunctionHelp() SIP_SKIP;
715  static void initVariableHelp() SIP_SKIP;
716 
717  friend class QgsOgcUtils;
718 };
719 
721 
722 #endif // QGSEXPRESSION_H
Class for parsing and evaluation of expressions (formerly called "search strings").
QString errorMsg
The message for the error at this location.
Details about any parser errors that were found when parsing the expression.
Container of fields for a vector layer.
Definition: qgsfields.h:42
A geometry is the spatial representation of a feature.
Definition: qgsgeometry.h:104
The feature class encapsulates a single feature including its id, geometry and a list of field/values...
Definition: qgsfeature.h:54
Q_DECLARE_METATYPE(QModelIndex)
#define SIP_SKIP
Definition: qgis_sip.h:119
Expression contexts are used to encapsulate the parameters around which a QgsExpression should be eva...
Abstract base class for all nodes that can appear in an expression.
Encapsulate a field in an attribute table or data source.
Definition: qgsfield.h:48
DistanceUnit
Units of distance.
Definition: qgsunittypes.h:53
A general purpose distance and area calculator, capable of performing ellipsoid based calculations...
A abstract base class for defining QgsExpression functions.
#define SIP_OUT
Definition: qgis_sip.h:51
This is the base class for vector data providers.
Represents a vector layer which manages a vector based data sets.
QList< const T * > findNodes() const
Returns a list of all nodes of the given class which are used in this expression. ...
The QgsOgcUtils class provides various utility functions for conversion between OGC (Open Geospatial ...
Definition: qgsogcutils.h:50
AreaUnit
Units of area.
Definition: qgsunittypes.h:79