Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
tags helping to find the correct function are integrated into the hel…
…p of the expression

defined in the json files and used by the expression builder to find the function (not using as alias)
  • Loading branch information
signedav committed Dec 3, 2019
1 parent a4a32fa commit 7fbf2c8
Show file tree
Hide file tree
Showing 9 changed files with 65 additions and 53 deletions.
9 changes: 9 additions & 0 deletions python/core/auto_generated/expression/qgsexpression.sip.in
Expand Up @@ -535,6 +535,15 @@ Returns the help text for a specified function.
.. seealso:: :py:func:`variableHelpText`

.. seealso:: :py:func:`formatVariableHelp`
%End

static QStringList tags( QString name );
%Docstring
Returns a string list of search tags for a specified function.

:param name: function name

.. versionadded:: 3.12
%End

static QString variableHelpText( const QString &variableName );
Expand Down
17 changes: 4 additions & 13 deletions python/core/auto_generated/expression/qgsexpressionfunction.sip.in
Expand Up @@ -84,8 +84,7 @@ should not be checked while determining referenced columns for the expression.
const QString &helpText = QString(),
bool lazyEval = false,
bool handlesNull = false,
bool isContextual = false,
const QStringList &searchTags = QStringList() );
bool isContextual = false );
%Docstring
Constructor for function which uses unnamed parameters
%End
Expand All @@ -96,8 +95,7 @@ Constructor for function which uses unnamed parameters
const QString &helpText = QString(),
bool lazyEval = false,
bool handlesNull = false,
bool isContextual = false,
const QStringList &searchTags = QStringList() );
bool isContextual = false );
%Docstring
Constructor for function which uses unnamed parameters and group list

Expand All @@ -110,8 +108,7 @@ Constructor for function which uses unnamed parameters and group list
const QString &helpText = QString(),
bool lazyEval = false,
bool handlesNull = false,
bool isContextual = false,
const QStringList &searchTags = QStringList() );
bool isContextual = false );
%Docstring
Constructor for function which uses named parameter list.

Expand All @@ -124,8 +121,7 @@ Constructor for function which uses named parameter list.
const QString &helpText = QString(),
bool lazyEval = false,
bool handlesNull = false,
bool isContextual = false,
const QStringList &searchTags = QStringList() );
bool isContextual = false );
%Docstring
Constructor for function which uses named parameter list and group list.

Expand Down Expand Up @@ -246,11 +242,6 @@ Returns a list of the groups the function belongs to.
const QString helpText() const;
%Docstring
The help text for the function.
%End

QStringList searchTags() const;
%Docstring
The search tags to find the function
%End

virtual QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent, const QgsExpressionNodeFunction *node ) = 0;
Expand Down
19 changes: 19 additions & 0 deletions src/core/expression/qgsexpression.cpp
Expand Up @@ -652,6 +652,25 @@ QString QgsExpression::helpText( QString name )
return helpContents;
}

QStringList QgsExpression::tags( QString name )
{
QStringList tags = QStringList();

QgsExpression::initFunctionHelp();

if ( sFunctionHelpTexts()->contains( name ) )
{
const Help &f = ( *sFunctionHelpTexts() )[ name ];

for ( const HelpVariant &v : qgis::as_const( f.mVariants ) )
{
tags << v.mTags;
}
}

return tags;
}

void QgsExpression::initVariableHelp()
{
if ( !sVariableHelpTexts()->isEmpty() )
Expand Down
7 changes: 7 additions & 0 deletions src/core/expression/qgsexpression.h
Expand Up @@ -567,6 +567,13 @@ class CORE_EXPORT QgsExpression
*/
static QString helpText( QString name );

/**
* Returns a string list of search tags for a specified function.
* \param name function name
* \since QGIS 3.12
*/
static QStringList tags( QString name );

/**
* Returns the help text for a specified variable.
* \param variableName name of variable
Expand Down
5 changes: 4 additions & 1 deletion src/core/expression/qgsexpression_p.h
Expand Up @@ -116,13 +116,15 @@ struct HelpVariant
const QList<HelpArg> &arguments = QList<HelpArg>(),
bool variableLenArguments = false,
const QList<HelpExample> &examples = QList<HelpExample>(),
const QString &notes = QString() )
const QString &notes = QString(),
const QStringList &tags = QStringList() )
: mName( name )
, mDescription( description )
, mArguments( arguments )
, mVariableLenArguments( variableLenArguments )
, mExamples( examples )
, mNotes( notes )
, mTags( tags )
{}

QString mName;
Expand All @@ -131,6 +133,7 @@ struct HelpVariant
bool mVariableLenArguments;
QList<HelpExample> mExamples;
QString mNotes;
QStringList mTags;
};


Expand Down
13 changes: 6 additions & 7 deletions src/core/expression/qgsexpressionfunction.cpp
Expand Up @@ -157,9 +157,8 @@ QgsStaticExpressionFunction::QgsStaticExpressionFunction( const QString &fnname,
const std::function < QSet<QString>( const QgsExpressionNodeFunction *node ) > &referencedColumns,
bool lazyEval,
const QStringList &aliases,
bool handlesNull,
const QStringList &searchTags )
: QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, false, searchTags )
bool handlesNull )
: QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, false )
, mFnc( fcn )
, mAliases( aliases )
, mUsesGeometry( false )
Expand Down Expand Up @@ -5962,8 +5961,8 @@ const QList<QgsExpressionFunction *> &QgsExpression::Functions()
<< new QgsStaticExpressionFunction( QStringLiteral( "array" ), -1, fcnArray, QStringLiteral( "Arrays" ), QString(), false, QSet<QString>(), false, QStringList(), true )
<< new QgsStaticExpressionFunction( QStringLiteral( "array_sort" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "ascending" ), true, true ), fcnArraySort, QStringLiteral( "Arrays" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "array_length" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array" ) ), fcnArrayLength, QStringLiteral( "Arrays" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "array_contains" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "value" ) ), fcnArrayContains, QStringLiteral( "Arrays" ), QString(), false, QSet<QString>(), false, QStringList(), false, QStringList() << QStringLiteral( "exists" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "array_all" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array_a" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "array_b" ) ), fcnArrayAll, QStringLiteral( "Arrays" ), QString(), false, QSet<QString>(), false, QStringList(), false, QStringList() << QStringLiteral( "contains" ) << QStringLiteral( "exists" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "array_contains" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "value" ) ), fcnArrayContains, QStringLiteral( "Arrays" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "array_all" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array_a" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "array_b" ) ), fcnArrayAll, QStringLiteral( "Arrays" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "array_find" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "value" ) ), fcnArrayFind, QStringLiteral( "Arrays" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "array_get" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "pos" ) ), fcnArrayGet, QStringLiteral( "Arrays" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "array_first" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array" ) ), fcnArrayFirst, QStringLiteral( "Arrays" ) )
Expand All @@ -5978,8 +5977,8 @@ const QList<QgsExpressionFunction *> &QgsExpression::Functions()
<< new QgsStaticExpressionFunction( QStringLiteral( "array_reverse" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array" ) ), fcnArrayReverse, QStringLiteral( "Arrays" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "array_intersect" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array1" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "array2" ) ), fcnArrayIntersect, QStringLiteral( "Arrays" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "array_distinct" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array" ) ), fcnArrayDistinct, QStringLiteral( "Arrays" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "array_to_string" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "delimiter" ), true, "," ) << QgsExpressionFunction::Parameter( QStringLiteral( "emptyvalue" ), true, "" ), fcnArrayToString, QStringLiteral( "Arrays" ), QString(), false, QSet<QString>(), false, QStringList(), false, QStringList() << QStringLiteral( "concats" ) << QStringLiteral( "converts" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "string_to_array" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "string" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "delimiter" ), true, "," ) << QgsExpressionFunction::Parameter( QStringLiteral( "emptyvalue" ), true, "" ), fcnStringToArray, QStringLiteral( "Arrays" ), QString(), false, QSet<QString>(), false, QStringList(), false, QStringList() << QStringLiteral( "splits" ) << QStringLiteral( "converts" ) << QStringLiteral( "seperates" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "array_to_string" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "array" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "delimiter" ), true, "," ) << QgsExpressionFunction::Parameter( QStringLiteral( "emptyvalue" ), true, "" ), fcnArrayToString, QStringLiteral( "Arrays" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "string_to_array" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "string" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "delimiter" ), true, "," ) << QgsExpressionFunction::Parameter( QStringLiteral( "emptyvalue" ), true, "" ), fcnStringToArray, QStringLiteral( "Arrays" ) )
<< new QgsStaticExpressionFunction( QStringLiteral( "generate_series" ), QgsExpressionFunction::ParameterList() << QgsExpressionFunction::Parameter( QStringLiteral( "start" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "stop" ) ) << QgsExpressionFunction::Parameter( QStringLiteral( "step" ), true, 1.0 ), fcnGenerateSeries, QStringLiteral( "Arrays" ) )

//functions for maps
Expand Down
38 changes: 11 additions & 27 deletions src/core/expression/qgsexpressionfunction.h
Expand Up @@ -110,16 +110,14 @@ class CORE_EXPORT QgsExpressionFunction
const QString &helpText = QString(),
bool lazyEval = false,
bool handlesNull = false,
bool isContextual = false,
const QStringList &searchTags = QStringList() )
bool isContextual = false )
: mName( fnname )
, mParams( params )
, mGroups( group.isEmpty() ? QStringList() : QStringList() << group )
, mHelpText( helpText )
, mLazyEval( lazyEval )
, mHandlesNull( handlesNull )
, mIsContextual( isContextual )
, mSearchTags( searchTags )
{
}

Expand All @@ -133,16 +131,14 @@ class CORE_EXPORT QgsExpressionFunction
const QString &helpText = QString(),
bool lazyEval = false,
bool handlesNull = false,
bool isContextual = false,
const QStringList &searchTags = QStringList() )
bool isContextual = false )
: mName( fnname )
, mParams( params )
, mGroups( groups )
, mHelpText( helpText )
, mLazyEval( lazyEval )
, mHandlesNull( handlesNull )
, mIsContextual( isContextual )
, mSearchTags( searchTags )
{
}

Expand All @@ -156,8 +152,7 @@ class CORE_EXPORT QgsExpressionFunction
const QString &helpText = QString(),
bool lazyEval = false,
bool handlesNull = false,
bool isContextual = false,
const QStringList &searchTags = QStringList() )
bool isContextual = false )
: mName( fnname )
, mParams( 0 )
, mParameterList( params )
Expand All @@ -166,7 +161,6 @@ class CORE_EXPORT QgsExpressionFunction
, mLazyEval( lazyEval )
, mHandlesNull( handlesNull )
, mIsContextual( isContextual )
, mSearchTags( searchTags )
{}

/**
Expand All @@ -179,8 +173,7 @@ class CORE_EXPORT QgsExpressionFunction
const QString &helpText = QString(),
bool lazyEval = false,
bool handlesNull = false,
bool isContextual = false,
const QStringList &searchTags = QStringList() )
bool isContextual = false )
: mName( fnname )
, mParams( 0 )
, mParameterList( params )
Expand All @@ -189,7 +182,6 @@ class CORE_EXPORT QgsExpressionFunction
, mLazyEval( lazyEval )
, mHandlesNull( handlesNull )
, mIsContextual( isContextual )
, mSearchTags( searchTags )
{}

virtual ~QgsExpressionFunction() = default;
Expand Down Expand Up @@ -300,9 +292,6 @@ class CORE_EXPORT QgsExpressionFunction
//! The help text for the function.
const QString helpText() const;

//! The search tags to find the function
QStringList searchTags() const { return mSearchTags; }

/**
* Returns result of evaluating the function.
* \param values list of values passed to the function
Expand Down Expand Up @@ -349,7 +338,6 @@ class CORE_EXPORT QgsExpressionFunction
bool mLazyEval;
bool mHandlesNull;
bool mIsContextual; //if true function is only available through an expression context
QStringList mSearchTags;
};

/**
Expand All @@ -374,9 +362,8 @@ class QgsStaticExpressionFunction : public QgsExpressionFunction
const QSet<QString> &referencedColumns = QSet<QString>(),
bool lazyEval = false,
const QStringList &aliases = QStringList(),
bool handlesNull = false,
const QStringList &searchTags = QStringList() )
: QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, false, searchTags )
bool handlesNull = false )
: QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, false )
, mFnc( fcn )
, mAliases( aliases )
, mUsesGeometry( usesGeometry )
Expand All @@ -396,9 +383,8 @@ class QgsStaticExpressionFunction : public QgsExpressionFunction
const QSet<QString> &referencedColumns = QSet<QString>(),
bool lazyEval = false,
const QStringList &aliases = QStringList(),
bool handlesNull = false,
const QStringList &searchTags = QStringList() )
: QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, false, searchTags )
bool handlesNull = false )
: QgsExpressionFunction( fnname, params, group, helpText, lazyEval, handlesNull, false )
, mFnc( fcn )
, mAliases( aliases )
, mUsesGeometry( usesGeometry )
Expand All @@ -425,8 +411,7 @@ class QgsStaticExpressionFunction : public QgsExpressionFunction
const std::function< QSet<QString>( const QgsExpressionNodeFunction *node )> &referencedColumns,
bool lazyEval = false,
const QStringList &aliases = QStringList(),
bool handlesNull = false,
const QStringList &searchTags = QStringList() );
bool handlesNull = false );

/**
* Static function for evaluation against a QgsExpressionContext, using a named list of parameter values and list
Expand All @@ -441,9 +426,8 @@ class QgsStaticExpressionFunction : public QgsExpressionFunction
const QSet<QString> &referencedColumns = QSet<QString>(),
bool lazyEval = false,
const QStringList &aliases = QStringList(),
bool handlesNull = false,
const QStringList &searchTags = QStringList() )
: QgsExpressionFunction( fnname, params, groups, helpText, lazyEval, handlesNull, false, searchTags )
bool handlesNull = false )
: QgsExpressionFunction( fnname, params, groups, helpText, lazyEval, handlesNull, false )
, mFnc( fcn )
, mAliases( aliases )
, mUsesGeometry( usesGeometry )
Expand Down
8 changes: 4 additions & 4 deletions src/gui/qgsexpressionbuilderwidget.cpp
Expand Up @@ -672,7 +672,7 @@ void QgsExpressionBuilderWidget::updateFunctionTree()
name += '(';
else if ( !name.startsWith( '$' ) )
name += QLatin1String( "()" );
registerItemForAllGroups( func->groups(), func->name(), ' ' + name + ' ', func->helpText(), QgsExpressionItem::ExpressionNode, mExpressionContext.isHighlightedFunction( func->name() ), 1, func->searchTags() );
registerItemForAllGroups( func->groups(), func->name(), ' ' + name + ' ', func->helpText(), QgsExpressionItem::ExpressionNode, mExpressionContext.isHighlightedFunction( func->name() ), 1, QgsExpression::tags( func->name() ) );
}

// load relation names
Expand Down Expand Up @@ -818,16 +818,16 @@ void QgsExpressionBuilderWidget::loadExpressionContext()
continue;
if ( func->params() != 0 )
name += '(';
registerItemForAllGroups( func->groups(), func->name(), ' ' + name + ' ', func->helpText(), QgsExpressionItem::ExpressionNode, mExpressionContext.isHighlightedFunction( func->name() ), 1, func->searchTags() );
registerItemForAllGroups( func->groups(), func->name(), ' ' + name + ' ', func->helpText(), QgsExpressionItem::ExpressionNode, mExpressionContext.isHighlightedFunction( func->name() ), 1, QgsExpression::tags( func->name() ) );
}
}

void QgsExpressionBuilderWidget::registerItemForAllGroups( const QStringList &groups, const QString &label, const QString &expressionText, const QString &helpText, QgsExpressionItem::ItemType type, bool highlightedItem, int sortOrder, const QStringList &searchTags )
void QgsExpressionBuilderWidget::registerItemForAllGroups( const QStringList &groups, const QString &label, const QString &expressionText, const QString &helpText, QgsExpressionItem::ItemType type, bool highlightedItem, int sortOrder, const QStringList &tags )
{
const auto constGroups = groups;
for ( const QString &group : constGroups )
{
registerItem( group, label, expressionText, helpText, type, highlightedItem, sortOrder, QIcon(), searchTags );
registerItem( group, label, expressionText, helpText, type, highlightedItem, sortOrder, QIcon(), tags );
}
}

Expand Down

0 comments on commit 7fbf2c8

Please sign in to comment.