MacroExpander Class | Extending Qt Creator Manual

Extending Qt Creator Manual | MacroExpander

Extending Qt Creator Manual 4.6.0

# MacroExpander Class

(Utils::MacroExpander)

The MacroExpander class manages Qt Creator 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. More...

Header: | #include <MacroExpander>

- List of all members, including inherited members

## Public Types

typedef | IntFunction
typedef | PrefixFunction
typedef | ResolverFunction
typedef | StringFunction

## Public Functions

QString | displayName() const
QString | expand(const QString &stringWithVariables) const
QByteArray | expand(const QByteArray &stringWithVariables) const
QString | expandProcessArgs(const QString &argsWithVariables) const
bool | isAccumulating() const
bool | isPrefixVariable(const QByteArray &variable) const
void | registerExtraResolver(const ResolverFunction &value)
void | registerFileVariables(const QByteArray &prefix, const QString &heading, const StringFunction &base, bool visibleInChooser = true)
void | registerIntVariable(const QByteArray &variable, const QString &description, const IntFunction &value)
void | registerPrefix(const QByteArray &prefix, const QString &description, const PrefixFunction &value)
void | registerSubProvider(const MacroExpanderProvider &provider)
void | registerVariable(const QByteArray &variable, const QString &description, const StringFunction &value, bool visibleInChooser = true)
void | setAccumulating(bool on)
void | setDisplayName(const QString &displayName)
MacroExpanderProviders | subProviders() const
QString | value(const QByteArray &variable, bool *found = 0) const
QString | variableDescription(const QByteArray &variable) const
QList<QByteArray> | visibleVariables() const

## Detailed Description

The MacroExpander class manages Qt Creator 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.

### 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 `CurrentDocument:FilePath` and `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.

### 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.

      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;
              }
          );
          [...]
      }

For variables that refer to a file, you should use the convenience function MacroExpander::registerFileVariables(). The functions take a variable prefix, like `MyFileVariable`, and automatically handle standardized postfixes like `:FilePath`, `:Path` and `:FileBaseName`, resulting in the combined variables, such as `MyFileVariable:FilePath`.

### 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 `MacroExpander::value("MyVariable")`, it is much more efficient to just ask directly with `MyPlugin::variableValue()`.)

#### 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.

#### 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 Qt Creator variables through MacroExpander::macroExpander().

There are several different ways to expand a string, covering the different use cases, listed here sorted by relevance:

- 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.
- 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.
- 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.
- 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.

## Member Type Documentation

### typedef MacroExpander::IntFunction

### typedef MacroExpander::PrefixFunction

### typedef MacroExpander::ResolverFunction

### typedef MacroExpander::StringFunction

## Member Function Documentation

### QString MacroExpander::displayName() const

See also setDisplayName().

### QString MacroExpander::expand(const QString &stringWithVariables) const

Returns stringWithVariables with all variables replaced by their values. See the MacroExpander overview documentation for other ways to expand variables.

See also MacroExpander and macroExpander().

### QByteArray MacroExpander::expand(const QByteArray &stringWithVariables) const

### QString MacroExpander::expandProcessArgs(const QString &argsWithVariables) const

### bool MacroExpander::isAccumulating() const

### bool MacroExpander::isPrefixVariable(const QByteArray &variable) const

### void MacroExpander::registerExtraResolver(const ResolverFunction &value)

### void MacroExpander::registerFileVariables(const QByteArray &prefix, const QString &heading, const StringFunction &base, bool visibleInChooser = true)

Convenience function to register several variables with the same prefix, that have a file as a value. Takes the prefix and registers variables like `prefix:FilePath` and `prefix:Path`, with descriptions that start with the given heading. For example `registerFileVariables("CurrentDocument", tr("Current Document"))` registers variables such as `CurrentDocument:FilePath` with description "Current Document: Full path including file name."

See also registerVariable(), registerIntVariable(), and registerPrefix().

### void MacroExpander::registerIntVariable(const QByteArray &variable, const QString &description, const IntFunction &value)

### void MacroExpander::registerPrefix(const QByteArray &prefix, const QString &description, const PrefixFunction &value)

### void MacroExpander::registerSubProvider(const MacroExpanderProvider &provider)

### void MacroExpander::registerVariable(const QByteArray &variable, const QString &description, const StringFunction &value, bool visibleInChooser = true)

Makes the given string-valued variable known to the variable manager, together with a localized description.

See also registerFileVariables(), registerIntVariable(), and registerPrefix().

### void MacroExpander::setAccumulating(bool on)

See also isAccumulating().

### void MacroExpander::setDisplayName(const QString &displayName)

See also displayName().

### MacroExpanderProviders MacroExpander::subProviders() const

### QString MacroExpander::value(const QByteArray &variable, bool *found = 0) const

Returns the value of the given variable. If found is given, it is set to true if the variable has a value at all, false if not.

### QString MacroExpander::variableDescription(const QByteArray &variable) const

Returns the description that was registered for the variable.

### QList<QByteArray> MacroExpander::visibleVariables() const

Returns all registered variable names.

See also registerVariable() and registerFileVariables().