macroexpander.cpp 16.4 KB
Newer Older
1 2
/****************************************************************************
**
3 4
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
5 6 7 8 9 10 11
**
** This file is part of Qt Creator.
**
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
12 13 14
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
15
**
16 17 18 19 20 21 22
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3 as published by the Free Software
** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-3.0.html.
23 24 25 26 27
**
****************************************************************************/

#include "macroexpander.h"

hjk's avatar
hjk committed
28
#include "algorithm.h"
29 30 31
#include "qtcassert.h"
#include "qtcprocess.h"
#include "stringutils.h"
hjk's avatar
hjk committed
32

33 34
#include <QCoreApplication>
#include <QDebug>
35
#include <QDir>
36 37 38
#include <QFileInfo>
#include <QMap>

39
namespace Utils {
40 41 42 43
namespace Internal {

const char kFilePathPostfix[] = ":FilePath";
const char kPathPostfix[] = ":Path";
44 45
const char kNativeFilePathPostfix[] = ":NativeFilePath";
const char kNativePathPostfix[] = ":NativePath";
46 47 48
const char kFileNamePostfix[] = ":FileName";
const char kFileBaseNamePostfix[] = ":FileBaseName";

hjk's avatar
hjk committed
49
class MacroExpanderPrivate : public AbstractMacroExpander
50 51
{
public:
52 53 54
    MacroExpanderPrivate()
        : m_accumulating(false), m_aborted(false), m_lockDepth(0)
    {}
hjk's avatar
hjk committed
55

56
    bool resolveMacro(const QString &name, QString *ret, QSet<AbstractMacroExpander *> &seen)
hjk's avatar
hjk committed
57
    {
58 59 60 61 62 63
        // Prevent loops:
        const int count = seen.count();
        seen.insert(this);
        if (seen.count() == count)
            return false;

hjk's avatar
hjk committed
64 65 66 67 68
        bool found;
        *ret = value(name.toUtf8(), &found);
        if (found)
            return true;

69
        found = Utils::anyOf(m_subProviders, [name, ret, &seen] (const MacroExpanderProvider &p) -> bool {
hjk's avatar
hjk committed
70
            MacroExpander *expander = p ? p() : 0;
71
            return expander && expander->d->resolveMacro(name, ret, seen);
hjk's avatar
hjk committed
72 73
        });

74 75 76 77 78 79 80
        if (found)
            return true;

        found = Utils::anyOf(m_extraResolvers, [name, ret] (const MacroExpander::ResolverFunction &resolver) {
            return resolver(name, ret);
        });

hjk's avatar
hjk committed
81 82 83
        if (found)
            return true;

84
        return this == globalMacroExpander()->d ? false : globalMacroExpander()->d->resolveMacro(name, ret, seen);
hjk's avatar
hjk committed
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
    }

    QString value(const QByteArray &variable, bool *found)
    {
        MacroExpander::StringFunction sf = m_map.value(variable);
        if (sf) {
            if (found)
                *found = true;
            return sf();
        }

        for (auto it = m_prefixMap.constBegin(); it != m_prefixMap.constEnd(); ++it) {
            if (variable.startsWith(it.key())) {
                MacroExpander::PrefixFunction pf = it.value();
                if (found)
                    *found = true;
                return pf(QString::fromUtf8(variable.mid(it.key().count())));
            }
        }
        if (found)
            *found = false;

        return QString();
    }

110 111
    QHash<QByteArray, MacroExpander::StringFunction> m_map;
    QHash<QByteArray, MacroExpander::PrefixFunction> m_prefixMap;
112
    QVector<MacroExpander::ResolverFunction> m_extraResolvers;
113
    QMap<QByteArray, QString> m_descriptions;
hjk's avatar
hjk committed
114
    QString m_displayName;
hjk's avatar
hjk committed
115 116
    QVector<MacroExpanderProvider> m_subProviders;
    bool m_accumulating;
117

118
    bool m_aborted;
119
    int m_lockDepth;
120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
};

} // Internal

using namespace Internal;

/*!
    \class Utils::MacroExpander
    \brief The MacroExpander class manages \QC wide variables, that a user
    can enter into many string settings. The variables are replaced by an actual value when the string
    is used, similar to how environment variables are expanded by a shell.

    \section1 Variables

    Variable names can be basically any string without dollar sign and braces,
    though it is recommended to only use 7-bit ASCII without special characters and whitespace.

    If there are several variables that contain different aspects of the same object,
    it is convention to give them the same prefix, followed by a colon and a postfix
    that describes the aspect.
    Examples of this are \c{CurrentDocument:FilePath} and \c{CurrentDocument:Selection}.

    When the variable manager is requested to replace variables in a string, it looks for
    variable names enclosed in %{ and }, like %{CurrentDocument:FilePath}.

    Environment variables are accessible using the %{Env:...} notation.
    For example, to access the SHELL environment variable, use %{Env:SHELL}.

    \note The names of the variables are stored as QByteArray. They are typically
    7-bit-clean. In cases where this is not possible, UTF-8 encoding is
    assumed.

    \section1 Providing Variable Values

    Plugins can register variables together with a description through registerVariable().
    A typical setup is to register variables in the Plugin::initialize() function.

    \code
    bool MyPlugin::initialize(const QStringList &arguments, QString *errorString)
    {
        [...]
        MacroExpander::registerVariable(
            "MyVariable",
            tr("The current value of whatever I want."));
            []() -> QString {
                QString value;
                // do whatever is necessary to retrieve the value
                [...]
                return value;
            }
        );
        [...]
    }
    \endcode
174 175


176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249
    For variables that refer to a file, you should use the convenience function
    MacroExpander::registerFileVariables().
    The functions take a variable prefix, like \c MyFileVariable,
    and automatically handle standardized postfixes like \c{:FilePath},
    \c{:Path} and \c{:FileBaseName}, resulting in the combined variables, such as
    \c{MyFileVariable:FilePath}.

    \section1 Providing and Expanding Parametrized Strings

    Though it is possible to just ask the variable manager for the value of some variable in your
    code, the preferred use case is to give the user the possibility to parametrize strings, for
    example for settings.

    (If you ever think about doing the former, think twice. It is much more efficient
    to just ask the plugin that provides the variable value directly, without going through
    string conversions, and through the variable manager which will do a large scale poll. To be
    more concrete, using the example from the Providing Variable Values section: instead of
    calling \c{MacroExpander::value("MyVariable")}, it is much more efficient to just ask directly
    with \c{MyPlugin::variableValue()}.)

    \section2 User Interface

    If the string that you want to parametrize is settable by the user, through a QLineEdit or
    QTextEdit derived class, you should add a variable chooser to your UI, which allows adding
    variables to the string by browsing through a list. See Core::VariableChooser for more
    details.

    \section2 Expanding Strings

    Expanding variable values in strings is done by "macro expanders".
    Utils::AbstractMacroExpander is the base class for these, and the variable manager
    provides an implementation that expands \QC variables through
    MacroExpander::macroExpander().

    There are several different ways to expand a string, covering the different use cases,
    listed here sorted by relevance:
    \list
    \li Using MacroExpander::expandedString(). This is the most comfortable way to get a string
        with variable values expanded, but also the least flexible one. If this is sufficient for
        you, use it.
    \li Using the Utils::expandMacros() functions. These take a string and a macro expander (for which
        you would use the one provided by the variable manager). Mostly the same as
        MacroExpander::expandedString(), but also has a variant that does the replacement inline
        instead of returning a new string.
    \li Using Utils::QtcProcess::expandMacros(). This expands the string while conforming to the
        quoting rules of the platform it is run on. Use this function with the variable manager's
        macro expander if your string will be passed as a command line parameter string to an
        external command.
    \li Writing your own macro expander that nests the variable manager's macro expander. And then
        doing one of the above. This allows you to expand additional "local" variables/macros,
        that do not come from the variable manager.
    \endlist

*/

/*!
 * \internal
 */
MacroExpander::MacroExpander()
{
    d = new MacroExpanderPrivate;
}

/*!
 * \internal
 */
MacroExpander::~MacroExpander()
{
    delete d;
}

/*!
 * \internal
 */
hjk's avatar
hjk committed
250
bool MacroExpander::resolveMacro(const QString &name, QString *ret) const
251
{
252 253
    QSet<AbstractMacroExpander*> seen;
    return d->resolveMacro(name, ret, seen);
254 255 256 257 258 259
}

/*!
 * Returns the value of the given \a variable. If \a found is given, it is
 * set to true if the variable has a value at all, false if not.
 */
hjk's avatar
hjk committed
260
QString MacroExpander::value(const QByteArray &variable, bool *found) const
261
{
hjk's avatar
hjk committed
262
    return d->value(variable, found);
263 264 265 266 267 268 269 270 271
}

/*!
 * Returns \a stringWithVariables with all variables replaced by their values.
 * See the MacroExpander overview documentation for other ways to expand variables.
 *
 * \sa MacroExpander
 * \sa macroExpander()
 */
hjk's avatar
hjk committed
272
QString MacroExpander::expand(const QString &stringWithVariables) const
273
{
274 275 276
    if (d->m_lockDepth == 0)
        d->m_aborted = false;

277
    if (d->m_lockDepth > 10) { // Limit recursion.
278
        d->m_aborted = true;
279
        return QString();
280
    }
281 282 283

    ++d->m_lockDepth;

hjk's avatar
hjk committed
284
    QString res = stringWithVariables;
hjk's avatar
hjk committed
285
    Utils::expandMacros(&res, d);
286 287 288

    --d->m_lockDepth;

289 290 291
    if (d->m_lockDepth == 0 && d->m_aborted)
        return tr("Infinite recursion error") + QLatin1String(": ") + stringWithVariables;

292 293 294
    return res;
}

hjk's avatar
hjk committed
295
QByteArray MacroExpander::expand(const QByteArray &stringWithVariables) const
296 297
{
    return expand(QString::fromLatin1(stringWithVariables)).toLatin1();
298 299
}

hjk's avatar
hjk committed
300 301 302 303 304
QString MacroExpander::expandProcessArgs(const QString &argsWithVariables) const
{
    return QtcProcess::expandMacros(argsWithVariables, d);
}

305 306 307 308 309 310 311 312
static QByteArray fullPrefix(const QByteArray &prefix)
{
    QByteArray result = prefix;
    if (!result.endsWith(':'))
        result.append(':');
    return result;
}

313 314 315 316 317 318 319 320 321 322 323 324
/*!
 * Makes the given string-valued \a prefix known to the variable manager,
 * together with a localized \a description.
 *
 * The \a value PrefixFunction will be called and gets the full variable name
 * with the prefix stripped as input.
 *
 * \sa registerVariables(), registerIntVariable(), registerFileVariables()
 */
void MacroExpander::registerPrefix(const QByteArray &prefix, const QString &description,
                                   const MacroExpander::PrefixFunction &value)
{
325
    QByteArray tmp = fullPrefix(prefix);
326 327 328 329 330 331 332 333 334 335 336
    d->m_descriptions.insert(tmp + "<value>", description);
    d->m_prefixMap.insert(tmp, value);
}

/*!
 * Makes the given string-valued \a variable known to the variable manager,
 * together with a localized \a description.
 *
 * \sa registerFileVariables(), registerIntVariable(), registerPrefix()
 */
void MacroExpander::registerVariable(const QByteArray &variable,
337
    const QString &description, const StringFunction &value, bool visibleInChooser)
338
{
339 340
    if (visibleInChooser)
        d->m_descriptions.insert(variable, description);
341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368
    d->m_map.insert(variable, value);
}

/*!
 * Makes the given integral-valued \a variable known to the variable manager,
 * together with a localized \a description.
 *
 * \sa registerVariable(), registerFileVariables(), registerPrefix()
 */
void MacroExpander::registerIntVariable(const QByteArray &variable,
    const QString &description, const MacroExpander::IntFunction &value)
{
    const MacroExpander::IntFunction valuecopy = value; // do not capture a reference in a lambda
    registerVariable(variable, description,
        [valuecopy]() { return QString::number(valuecopy ? valuecopy() : 0); });
}

/*!
 * Convenience function to register several variables with the same \a prefix, that have a file
 * as a value. Takes the prefix and registers variables like \c{prefix:FilePath} and
 * \c{prefix:Path}, with descriptions that start with the given \a heading.
 * For example \c{registerFileVariables("CurrentDocument", tr("Current Document"))} registers
 * variables such as \c{CurrentDocument:FilePath} with description
 * "Current Document: Full path including file name."
 *
 * \sa registerVariable(), registerIntVariable(), registerPrefix()
 */
void MacroExpander::registerFileVariables(const QByteArray &prefix,
hjk's avatar
hjk committed
369
    const QString &heading, const StringFunction &base, bool visibleInChooser)
370 371
{
    registerVariable(prefix + kFilePathPostfix,
372
         tr("%1: Full path including file name.").arg(heading),
hjk's avatar
hjk committed
373 374
         [base]() -> QString { QString tmp = base(); return tmp.isEmpty() ? QString() : QFileInfo(tmp).filePath(); },
         visibleInChooser);
375 376

    registerVariable(prefix + kPathPostfix,
377
         tr("%1: Full path excluding file name.").arg(heading),
hjk's avatar
hjk committed
378 379
         [base]() -> QString { QString tmp = base(); return tmp.isEmpty() ? QString() : QFileInfo(tmp).path(); },
         visibleInChooser);
380

381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396
    registerVariable(prefix + kNativeFilePathPostfix,
         tr("%1: Full path including file name, with native path separator (backslash on Windows).").arg(heading),
         [base]() -> QString {
             QString tmp = base();
             return tmp.isEmpty() ? QString() : QDir::toNativeSeparators(QFileInfo(tmp).filePath());
         },
         visibleInChooser);

    registerVariable(prefix + kNativePathPostfix,
         tr("%1: Full path excluding file name, with native path separator (backslash on Windows).").arg(heading),
         [base]() -> QString {
             QString tmp = base();
             return tmp.isEmpty() ? QString() : QDir::toNativeSeparators(QFileInfo(tmp).path());
         },
         visibleInChooser);

397
    registerVariable(prefix + kFileNamePostfix,
398
         tr("%1: File name without path.").arg(heading),
399
         [base]() -> QString { QString tmp = base(); return tmp.isEmpty() ? QString() : Utils::FileName::fromString(tmp).fileName(); },
hjk's avatar
hjk committed
400
         visibleInChooser);
401 402

    registerVariable(prefix + kFileBaseNamePostfix,
403
         tr("%1: File base name without path and suffix.").arg(heading),
hjk's avatar
hjk committed
404 405
         [base]() -> QString { QString tmp = base(); return tmp.isEmpty() ? QString() : QFileInfo(tmp).baseName(); },
         visibleInChooser);
406 407
}

408 409 410 411 412
void MacroExpander::registerExtraResolver(const MacroExpander::ResolverFunction &value)
{
    d->m_extraResolvers.append(value);
}

413 414 415 416 417 418
/*!
 * Returns all registered variable names.
 *
 * \sa registerVariable()
 * \sa registerFileVariables()
 */
419
QList<QByteArray> MacroExpander::visibleVariables() const
420
{
421
    return d->m_descriptions.keys();
422 423 424 425 426
}

/*!
 * Returns the description that was registered for the \a variable.
 */
hjk's avatar
hjk committed
427
QString MacroExpander::variableDescription(const QByteArray &variable) const
428 429
{
    return d->m_descriptions.value(variable);
430 431
}

432 433 434 435 436
bool MacroExpander::isPrefixVariable(const QByteArray &variable) const
{
    return d->m_prefixMap.contains(fullPrefix(variable));
}

437
MacroExpanderProviders MacroExpander::subProviders() const
hjk's avatar
hjk committed
438
{
439
    return d->m_subProviders;
hjk's avatar
hjk committed
440 441
}

hjk's avatar
hjk committed
442 443 444 445 446 447 448 449 450 451
QString MacroExpander::displayName() const
{
    return d->m_displayName;
}

void MacroExpander::setDisplayName(const QString &displayName)
{
    d->m_displayName = displayName;
}

hjk's avatar
hjk committed
452 453 454 455 456 457 458 459 460 461 462 463 464 465
void MacroExpander::registerSubProvider(const MacroExpanderProvider &provider)
{
    d->m_subProviders.append(provider);
}

bool MacroExpander::isAccumulating() const
{
    return d->m_accumulating;
}

void MacroExpander::setAccumulating(bool on)
{
    d->m_accumulating = on;
}
hjk's avatar
hjk committed
466 467 468 469 470 471

class GlobalMacroExpander : public MacroExpander
{
public:
    GlobalMacroExpander()
    {
472
        setDisplayName(MacroExpander::tr("Global variables"));
473
        registerPrefix("Env", MacroExpander::tr("Access environment variables."),
hjk's avatar
hjk committed
474 475 476 477 478 479 480 481 482 483 484 485 486
           [](const QString &value) { return QString::fromLocal8Bit(qgetenv(value.toLocal8Bit())); });
    }
};

/*!
 * Returns the expander for globally registered variables.
 */
MacroExpander *globalMacroExpander()
{
    static GlobalMacroExpander theGlobalExpander;
    return &theGlobalExpander;
}

487
} // namespace Utils