Macros: Add better examples for "prefix" variablesHEADmaster

Variables registered with `registerPrefix` are shown in the variable
chooser as `Prefix:<value>`, and that was used to show the "current
value" as the example in the variable chooser.

Add an explicit "example value" to the registerPrefix calls that is used
instead of "<value>" for the expanded example in the variable chooser.

Fixes: QTCREATORBUG-33120
Change-Id: I4cc522856bf9a7fefeea2ea498de5f67d503b86a
Reviewed-by: Alessandro Portale <[email protected]>

12 files changed, 125 insertions, 73 deletions

diff --git a/src/libs/utils/macroexpander.cpp b/src/libs/utils/macroexpander.cpp
index 71041422905..cf63a8974bb 100644
--- a/src/libs/utils/macroexpander.cpp
+++ b/src/libs/utils/macroexpander.cpp
@@ -6,6 +6,7 @@
 #include "algorithm.h"
 #include "commandline.h"
 #include "environment.h"
+#include "hostosinfo.h"
 #include "stringutils.h"
 #include "utilstr.h"
 
@@ -186,7 +187,12 @@ public:
     QHash<QByteArray, MacroExpander::StringFunction> m_map;
     QHash<QByteArray, MacroExpander::PrefixFunction> m_prefixMap;
     QList<MacroExpander::ResolverFunction> m_extraResolvers;
-    QMap<QByteArray, QString> m_descriptions;
+    struct Description
+    {
+        QString description;
+        QByteArray exampleUsage;
+    };
+    QMap<QByteArray, Description> m_descriptions;
     QString m_displayName;
     QList<MacroExpanderProvider> m_subProviders;
     bool m_accumulating = false;
@@ -440,7 +446,9 @@ static QByteArray fullPrefix(const QByteArray &prefix)
 
 /*!
  * Makes the given string-valued \a prefix known to the variable manager,
- * together with a localized \a description.
+ * together with a localized \a description. Provide an example for the
+ * value after the prefix in \a {examplePostfix}. That is used to show
+ * an expanded example in the variable chooser.
  *
  * The \a value \c PrefixFunction will be called and gets the full variable name
  * with the prefix stripped as input. It is displayed to users if \a visible is
@@ -450,13 +458,17 @@ static QByteArray fullPrefix(const QByteArray &prefix)
  *
  * \sa registerVariable(), registerIntVariable(), registerFileVariables()
  */
-void MacroExpander::registerPrefix(const QByteArray &prefix, const QString &description,
-                                   const MacroExpander::PrefixFunction &value, bool visible,
-                                   bool availableForExpansion)
+void MacroExpander::registerPrefix(
+    const QByteArray &prefix,
+    const QByteArray &examplePostfix,
+    const QString &description,
+    const MacroExpander::PrefixFunction &value,
+    bool visible,
+    bool availableForExpansion)
 {
     QByteArray tmp = fullPrefix(prefix);
     if (visible)
-        d->m_descriptions.insert(tmp + "<value>", description);
+        d->m_descriptions.insert(tmp + "<value>", {description, tmp + examplePostfix});
     if (availableForExpansion)
         d->m_prefixMap.insert(tmp, value);
 }
@@ -480,7 +492,7 @@ void MacroExpander::registerVariable(
     bool availableForExpansion)
 {
     if (visibleInChooser)
-        d->m_descriptions.insert(variable, description);
+        d->m_descriptions.insert(variable, {description, variable});
     if (availableForExpansion)
         d->m_map.insert(variable, value);
 }
@@ -587,7 +599,12 @@ QList<QByteArray> MacroExpander::visibleVariables() const
  */
 QString MacroExpander::variableDescription(const QByteArray &variable) const
 {
-    return d->m_descriptions.value(variable);
+    return d->m_descriptions.value(variable).description;
+}
+
+QByteArray MacroExpander::variableExampleUsage(const QByteArray &variable) const
+{
+    return d->m_descriptions.value(variable).exampleUsage;
 }
 
 bool MacroExpander::isPrefixVariable(const QByteArray &variable) const
@@ -636,8 +653,11 @@ public:
     GlobalMacroExpander()
     {
         setDisplayName(Tr::tr("Global variables"));
-        registerPrefix("Env", Tr::tr("Access environment variables."),
-                       [](const QString &value) { return qtcEnvironmentVariable(value); });
+        registerPrefix(
+            "Env",
+            HostOsInfo::isWindowsHost() ? "USERNAME" : "USER",
+            Tr::tr("Access environment variables."),
+            [](const QString &value) { return qtcEnvironmentVariable(value); });
     }
 };
 
diff --git a/src/libs/utils/macroexpander.h b/src/libs/utils/macroexpander.h
index 439697aec3b..963f094439b 100644
--- a/src/libs/utils/macroexpander.h
+++ b/src/libs/utils/macroexpander.h
@@ -48,6 +48,7 @@ public:
 
     void registerPrefix(
         const QByteArray &prefix,
+        const QByteArray &examplePostfix,
         const QString &description,
         const PrefixFunction &value,
         bool visible = true,
@@ -68,6 +69,7 @@ public:
 
     QList<QByteArray> visibleVariables() const;
     QString variableDescription(const QByteArray &variable) const;
+    QByteArray variableExampleUsage(const QByteArray &variable) const;
     bool isPrefixVariable(const QByteArray &variable) const;
 
     MacroExpanderProviders subProviders() const;
diff --git a/src/libs/utils/variablechooser.cpp b/src/libs/utils/variablechooser.cpp
index 71da329831b..52fe3d0d9a9 100644
--- a/src/libs/utils/variablechooser.cpp
+++ b/src/libs/utils/variablechooser.cpp
@@ -186,10 +186,12 @@ public:
 
         if (role == CurrentValueDisplayRole) {
             QString description = m_expander->variableDescription(m_variable);
-            const QString value = m_expander->value(m_variable).toHtmlEscaped();
+            const QByteArray exampleUsage = m_expander->variableExampleUsage(m_variable);
+            const QString value = m_expander->value(exampleUsage).toHtmlEscaped();
             if (!value.isEmpty())
                 description += QLatin1String("<p>")
-                        + Tr::tr("Current Value: %1").arg(value);
+                               + Tr::tr("Current Value of %{%1}: %2")
+                                     .arg(QString::fromUtf8(exampleUsage), value);
             return description;
         }
 
diff --git a/src/plugins/coreplugin/coreplugin.cpp b/src/plugins/coreplugin/coreplugin.cpp
index 1ee4dec6354..eb7e90b68ac 100644
--- a/src/plugins/coreplugin/coreplugin.cpp
+++ b/src/plugins/coreplugin/coreplugin.cpp
@@ -369,17 +369,26 @@ Result<> CorePlugin::initialize(const QStringList &arguments)
                                Tr::tr("The directory where %1 puts custom user data.")
                                    .arg(QGuiApplication::applicationDisplayName()),
                                [] { return ICore::userResourcePath().toUrlishString(); });
-    expander->registerPrefix("CurrentDate:", Tr::tr("The current date (QDate formatstring)."),
-                             [](const QString &fmt) { return QDate::currentDate().toString(fmt); });
-    expander->registerPrefix("CurrentTime:", Tr::tr("The current time (QTime formatstring)."),
-                             [](const QString &fmt) { return QTime::currentTime().toString(fmt); });
+    expander->registerPrefix(
+        "CurrentDate:",
+        "dd.MM.yyyy",
+        Tr::tr("The current date (QDate formatstring)."),
+        [](const QString &fmt) { return QDate::currentDate().toString(fmt); });
+    expander->registerPrefix(
+        "CurrentTime:",
+        "hh:mm:ss",
+        Tr::tr("The current time (QTime formatstring)."),
+        [](const QString &fmt) { return QTime::currentTime().toString(fmt); });
     expander->registerVariable("UUID", Tr::tr("Generate a new UUID."),
                                [] { return QUuid::createUuid().toString(); });
 
-    expander->registerPrefix("#:", Tr::tr("A comment."), [](const QString &) { return QString(); });
-    expander->registerPrefix("Asciify:",
-                             Tr::tr("Convert string to pure ASCII."),
-                             [expander](const QString &s) { return asciify(expander->expand(s)); });
+    expander->registerPrefix("#:", "<comment>", Tr::tr("A comment."), [](const QString &) {
+        return QString();
+    });
+    expander->registerPrefix(
+        "Asciify:", "éΩ", Tr::tr("Convert string to pure ASCII."), [expander](const QString &s) {
+            return asciify(expander->expand(s));
+        });
 
     registerStandardLocation(expander, QStandardPaths::DocumentsLocation);
     registerStandardLocation(expander, QStandardPaths::GenericDataLocation);
diff --git a/src/plugins/coreplugin/jsexpander.cpp b/src/plugins/coreplugin/jsexpander.cpp
index 6ae8eb2bdc4..284309fa460 100644
--- a/src/plugins/coreplugin/jsexpander.cpp
+++ b/src/plugins/coreplugin/jsexpander.cpp
@@ -68,10 +68,12 @@ void JsExpander::registerForExpander(Utils::MacroExpander *macroExpander)
 {
     macroExpander->registerPrefix(
         "JS",
-        Tr::tr("Evaluate simple JavaScript statements.<br>"
-               "Literal '}' characters must be escaped as \"\\}\", "
-               "'\\' characters must be escaped as \"\\\\\", "
-               "and \"%{\" must be escaped as \"%\\{\"."),
+        "1+1",
+        Tr::tr(
+            "Evaluate simple JavaScript statements.<br>"
+            "Literal '}' characters must be escaped as \"\\}\", "
+            "'\\' characters must be escaped as \"\\\\\", "
+            "and \"%{\" must be escaped as \"%\\{\"."),
         [this](QString in) -> QString {
             QString errorMessage;
             QString result = evaluate(in, &errorMessage);
diff --git a/src/plugins/git/gitplugin.cpp b/src/plugins/git/gitplugin.cpp
index 9532815716c..9dfbd9207e6 100644
--- a/src/plugins/git/gitplugin.cpp
+++ b/src/plugins/git/gitplugin.cpp
@@ -561,6 +561,7 @@ GitPluginPrivate::GitPluginPrivate()
 
     Utils::globalMacroExpander()->registerPrefix(
         "Git:Config",
+        "user.name",
         Tr::tr("Access git config variables."),
         [this](const QString &value) {
             return gitClient().readConfigValue(currentState().topLevel(), value);
diff --git a/src/plugins/lua/luaexpander.cpp b/src/plugins/lua/luaexpander.cpp
index 46731a7390b..8963f6f6d05 100644
--- a/src/plugins/lua/luaexpander.cpp
+++ b/src/plugins/lua/luaexpander.cpp
@@ -80,11 +80,13 @@ void setupLuaExpander(MacroExpander *expander)
 {
     expander->registerPrefix(
         "Lua",
-        Tr::tr("Evaluate simple Lua statements.<br>"
-               "Literal '}' characters must be escaped as \"\\}\", "
-               "'\\' characters must be escaped as \"\\\\\", "
-               "'#' characters must be escaped as \"\\#\", "
-               "and \"%{\" must be escaped as \"%\\{\"."),
+        "1+1",
+        Tr::tr(
+            "Evaluate simple Lua statements.<br>"
+            "Literal '}' characters must be escaped as \"\\}\", "
+            "'\\' characters must be escaped as \"\\\\\", "
+            "'#' characters must be escaped as \"\\#\", "
+            "and \"%{\" must be escaped as \"%\\{\"."),
         [expander](const QString &statement) -> QString {
             if (statement.isEmpty())
                 return Tr::tr("No Lua statement to evaluate.");
diff --git a/src/plugins/projectexplorer/buildconfiguration.cpp b/src/plugins/projectexplorer/buildconfiguration.cpp
index 9db9a86e4f3..eff47d4ad03 100644
--- a/src/plugins/projectexplorer/buildconfiguration.cpp
+++ b/src/plugins/projectexplorer/buildconfiguration.cpp
@@ -211,9 +211,11 @@ BuildConfiguration::BuildConfiguration(Target *target, Utils::Id id)
                                     [this] { return buildDirectory(); });
     expander->registerVariable("BuildConfig:Name", Tr::tr("Name of the build configuration"),
             [this] { return displayName(); });
-    expander->registerPrefix("BuildConfig:Env",
-                             Tr::tr("Variables in the build configuration's environment"),
-                             [this](const QString &var) { return environment().expandedValueForKey(var); });
+    expander->registerPrefix(
+        "BuildConfig:Env",
+        "USER",
+        Tr::tr("Variables in the build configuration's environment"),
+        [this](const QString &var) { return environment().expandedValueForKey(var); });
 
     connect(Core::ICore::instance(), &Core::ICore::systemEnvironmentChanged,
             this, &BuildConfiguration::updateCacheAndEmitEnvironmentChanged);
diff --git a/src/plugins/projectexplorer/jsonwizard/jsonwizard.cpp b/src/plugins/projectexplorer/jsonwizard/jsonwizard.cpp
index eed1f584871..c94fee0c8bd 100644
--- a/src/plugins/projectexplorer/jsonwizard/jsonwizard.cpp
+++ b/src/plugins/projectexplorer/jsonwizard/jsonwizard.cpp
@@ -131,13 +131,16 @@ JsonWizard::JsonWizard()
         *ret = stringValue(name);
         return !ret->isNull();
     });
-    m_expander.registerPrefix("Exists", Tr::tr("Check whether a variable exists.<br>"
-                                           "Returns \"true\" if it does and an empty string if not."),
-                   [this](const QString &value) -> QString
-    {
-        const QString key = QString::fromLatin1("%{") + value + QLatin1Char('}');
-        return m_expander.expand(key) == key ? QString() : QLatin1String("true");
-    });
+    m_expander.registerPrefix(
+        "Exists",
+        "",
+        Tr::tr(
+            "Check whether a variable exists.<br>"
+            "Returns \"true\" if it does and an empty string if not."),
+        [this](const QString &value) -> QString {
+            const QString key = QString::fromLatin1("%{") + value + QLatin1Char('}');
+            return m_expander.expand(key) == key ? QString() : QLatin1String("true");
+        });
     // override default JS macro by custom one that adds Wizard specific features
     m_jsExpander.registerObject("Wizard", new Internal::JsonWizardJsExtension(this));
     m_jsExpander.evaluate("var value = Wizard.value");
diff --git a/src/plugins/projectexplorer/project.cpp b/src/plugins/projectexplorer/project.cpp
index c783045cad7..30e5a0228a1 100644
--- a/src/plugins/projectexplorer/project.cpp
+++ b/src/plugins/projectexplorer/project.cpp
@@ -1335,15 +1335,16 @@ void Project::addVariablesToMacroExpander(const QByteArray &prefix,
                                        return bc->buildDirectory().toUserOutput();
                                    return {};
                                });
-    expander->registerPrefix(fullPrefix + "BuildConfig:Env",
-                             //: %1 is something like "Active project"
-                             ::PE::Tr::tr("%1: Variables in the active build environment.")
-                                 .arg(descriptor),
-                             [bcGetter](const QString &var) -> QString {
-                                 if (BuildConfiguration *const bc = bcGetter())
-                                     return bc->environment().expandedValueForKey(var);
-                                 return {};
-                             });
+    expander->registerPrefix(
+        fullPrefix + "BuildConfig:Env",
+        "USER",
+        //: %1 is something like "Active project"
+        ::PE::Tr::tr("%1: Variables in the active build environment.").arg(descriptor),
+        [bcGetter](const QString &var) -> QString {
+            if (BuildConfiguration *const bc = bcGetter())
+                return bc->environment().expandedValueForKey(var);
+            return {};
+        });
 
     expander->registerVariable(fullPrefix + "RunConfig:Name",
                                //: %1 is something like "Active project"
@@ -1363,19 +1364,19 @@ void Project::addVariablesToMacroExpander(const QByteArray &prefix,
                                             return rc->commandLine().executable();
                                         return {};
                                     });
-    expander
-        ->registerPrefix(fullPrefix + "RunConfig:Env",
-                         //: %1 is something like "Active project"
-                         ::PE::Tr::tr(
-                             "%1: Variables in the environment of the active run configuration.")
-                             .arg(descriptor),
-                         [rcGetter](const QString &var) -> QString {
-                             if (const RunConfiguration *const rc = rcGetter()) {
-                                 if (const auto envAspect = rc->aspect<EnvironmentAspect>())
-                                     return envAspect->environment().expandedValueForKey(var);
-                             }
-                             return {};
-                         });
+    expander->registerPrefix(
+        fullPrefix + "RunConfig:Env",
+        "USER",
+        //: %1 is something like "Active project"
+        ::PE::Tr::tr("%1: Variables in the environment of the active run configuration.")
+            .arg(descriptor),
+        [rcGetter](const QString &var) -> QString {
+            if (const RunConfiguration *const rc = rcGetter()) {
+                if (const auto envAspect = rc->aspect<EnvironmentAspect>())
+                    return envAspect->environment().expandedValueForKey(var);
+            }
+            return {};
+        });
     expander->registerVariable(fullPrefix + "RunConfig:WorkingDir",
                                //: %1 is something like "Active project"
                                ::PE::Tr::tr(
diff --git a/src/plugins/projectexplorer/runconfiguration.cpp b/src/plugins/projectexplorer/runconfiguration.cpp
index fc7bdd9a39b..0b3d8d81a64 100644
--- a/src/plugins/projectexplorer/runconfiguration.cpp
+++ b/src/plugins/projectexplorer/runconfiguration.cpp
@@ -343,12 +343,17 @@ void RunConfiguration::setupMacroExpander(
     MacroExpander &exp, const RunConfiguration *rc, bool documentationOnly)
 {
     exp.registerPrefix(
-        "RunConfig:Env", Tr::tr("Variables in the run environment."), [rc](const QString &var) {
+        "RunConfig:Env",
+        "USER",
+        Tr::tr("Variables in the run environment."),
+        [rc](const QString &var) {
             if (!rc)
                 return QString();
             const auto envAspect = rc->aspect<EnvironmentAspect>();
             return envAspect ? envAspect->environment().expandedValueForKey(var) : QString();
-        }, true, !documentationOnly);
+        },
+        true,
+        !documentationOnly);
 
     exp.registerVariable("RunConfig:Name", Tr::tr("The run configuration's name."), [rc] {
             return rc ? rc->displayName() : QString();
diff --git a/src/plugins/projectexplorer/toolchainkitaspect.cpp b/src/plugins/projectexplorer/toolchainkitaspect.cpp
index 5525ad95116..fcf300c71b6 100644
--- a/src/plugins/projectexplorer/toolchainkitaspect.cpp
+++ b/src/plugins/projectexplorer/toolchainkitaspect.cpp
@@ -367,16 +367,19 @@ void ToolchainKitAspectFactory::addToMacroExpander(Kit *kit, MacroExpander *expa
                                });
 
     // After 4.2
-    expander->registerPrefix("Compiler:Name", Tr::tr("Compiler for different languages"),
-                             [kit](const QString &ls) {
-                                 const Toolchain *tc = ToolchainKitAspect::toolchain(kit, findLanguage(ls));
-                                 return tc ? tc->displayName() : Tr::tr("None", "No compiler");
-                             });
-    expander->registerPrefix("Compiler:Executable", Tr::tr("Compiler executable for different languages"),
-                             [kit](const QString &ls) {
-                                 const Toolchain *tc = ToolchainKitAspect::toolchain(kit, findLanguage(ls));
-                                 return tc ? tc->compilerCommand().path() : QString();
-                             });
+    expander->registerPrefix(
+        "Compiler:Name", "C", Tr::tr("Compiler for different languages"), [kit](const QString &ls) {
+            const Toolchain *tc = ToolchainKitAspect::toolchain(kit, findLanguage(ls));
+            return tc ? tc->displayName() : Tr::tr("None", "No compiler");
+        });
+    expander->registerPrefix(
+        "Compiler:Executable",
+        "C",
+        Tr::tr("Compiler executable for different languages"),
+        [kit](const QString &ls) {
+            const Toolchain *tc = ToolchainKitAspect::toolchain(kit, findLanguage(ls));
+            return tc ? tc->compilerCommand().path() : QString();
+        });
 }
 
 QList<OutputLineParser *> ToolchainKitAspectFactory::createOutputParsers(const Kit *k) const