qdoc: Add regular expression matching to macros

This commit adds support for a special format (.match) option
to QDoc macros. The use case is to do additional regular
expression pattern matching for expanded macros; For example,

macro.qtminorversion       = "$QT_VER"
macro.qtminorversion.match = "\\d+\\.(\\d+)"

creates a macro that expands to the minor version based on the
QT_VER environment variable.

A macro that defines a match pattern outputs all capture groups
concatenated together, or the exact matched string if the
pattern does not contain any capture groups (parentheses).

Task-number: QTBUG-67818
Change-Id: I8dd5b08a05555b381d100e30aaef7a9930710993
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Martin Smith <martin.smith@qt.io>

2 files changed, 58 insertions, 20 deletions

diff --git a/src/qdoc/doc.cpp b/src/qdoc/doc.cpp
index 2b25f3b3a..80e440086 100644
--- a/src/qdoc/doc.cpp
+++ b/src/qdoc/doc.cpp
@@ -471,7 +471,7 @@ private:
     CodeMarker *quoteFromFile();
     bool expandMacro();
     void expandMacro(const QString& name, const QString& def, int numParams);
-    QString expandMacroToString(const QString &name, const QString &def, int numParams);
+    QString expandMacroToString(const QString &name, const QString &def, int numParams, const QString &matchExpr);
     Doc::Sections getSectioningUnit();
     QString getArgument(bool verbatim = false);
     QString getBracedArgument(bool verbatim);
@@ -1345,32 +1345,40 @@ void DocParser::parse(const QString& source,
                         const Macro &macro = macroHash()->value(cmdStr);
                         int numPendingFi = 0;
                         QStringMap::ConstIterator d;
+                        int numFormatDefs = 0;
+                        QString matchExpr;
                         d = macro.otherDefs.constBegin();
                         while (d != macro.otherDefs.constEnd()) {
-                            append(Atom::FormatIf, d.key());
-                            expandMacro(cmdStr, *d, macro.numParams);
-                            ++d;
-
-                            if (d == macro.otherDefs.constEnd()) {
-                                append(Atom::FormatEndif);
+                            if (d.key() == "match") {
+                                matchExpr = d.value();
+                                ++d;
                             } else {
-                                append(Atom::FormatElse);
-                                numPendingFi++;
+                                append(Atom::FormatIf, d.key());
+                                expandMacro(cmdStr, *d, macro.numParams);
+                                ++d;
+                                ++numFormatDefs;
+                                if (d == macro.otherDefs.constEnd()) {
+                                    append(Atom::FormatEndif);
+                                } else {
+                                    append(Atom::FormatElse);
+                                    numPendingFi++;
+                                }
                             }
                         }
                         while (numPendingFi-- > 0)
                             append(Atom::FormatEndif);
 
                         if (!macro.defaultDef.isEmpty()) {
-                            if (!macro.otherDefs.isEmpty()) {
+                            if (numFormatDefs > 0) {
                                 macro.defaultDefLocation.warning(
                                             tr("Macro cannot have both "
-                                               "format-specific and qdoc- "
+                                               "format-specific and qdoc-"
                                                "syntax definitions"));
                             } else {
                                 QString expanded = expandMacroToString(cmdStr,
                                                                        macro.defaultDef,
-                                                                       macro.numParams);
+                                                                       macro.numParams,
+                                                                       matchExpr);
                                 input_.replace(backslashPos, endPos - backslashPos, expanded);
                                 len = input_.length();
                                 pos = backslashPos;
@@ -2129,13 +2137,15 @@ bool DocParser::expandMacro()
     while (pos < (int) input_.length() && input_[pos].isLetterOrNumber())
         cmdStr += input_[pos++];
 
+    endPos = pos;
     if (!cmdStr.isEmpty()) {
         if (macroHash()->contains(cmdStr)) {
             const Macro &macro = macroHash()->value(cmdStr);
             if (!macro.defaultDef.isEmpty()) {
                 QString expanded = expandMacroToString(cmdStr,
                                                        macro.defaultDef,
-                                                       macro.numParams);
+                                                       macro.numParams,
+                                                       macro.otherDefs.value("match"));
                 input_.replace(backslashPos, pos - backslashPos, expanded);
                 len = input_.length();
                 pos = backslashPos;
@@ -2202,15 +2212,14 @@ void DocParser::expandMacro(const QString &name,
     }
 }
 
-QString DocParser::expandMacroToString(const QString &name, const QString &def, int numParams)
+QString DocParser::expandMacroToString(const QString &name, const QString &def, int numParams, const QString &matchExpr)
 {
+    QString rawString;
+
     if (numParams == 0) {
-        return def;
-    }
-    else {
+        rawString = def;
+    } else {
         QStringList args;
-        QString rawString;
-
         for (int i = 0; i < numParams; i++) {
             if (numParams == 1 || isLeftBraceAhead()) {
                 args << getArgument(true);
@@ -2236,8 +2245,21 @@ QString DocParser::expandMacroToString(const QString &name, const QString &def,
                 rawString += def[j++];
             }
         }
+    }
+    if (matchExpr.isEmpty())
         return rawString;
+
+    QString result;
+    QRegExp re(matchExpr);
+    int capStart = (re.captureCount() > 0) ? 1 : 0;
+    int i = 0;
+    while ((i = re.indexIn(rawString, i)) != -1) {
+        for (int c = capStart; c <= re.captureCount(); ++c)
+            result += re.cap(c);
+        i += re.matchedLength();
     }
+
+    return result;
 }
 
 Doc::Sections DocParser::getSectioningUnit()
@@ -2331,7 +2353,6 @@ QString DocParser::getArgument(bool verbatim)
 
     int delimDepth = 0;
     int startPos = pos;
-    endPos = pos;
     QString arg = getBracedArgument(verbatim);
     if (arg.isEmpty()) {
         while ((pos < input_.length()) &&
diff --git a/src/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
index f60b5d8b5..0080c6a99 100644
--- a/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
+++ b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
@@ -767,6 +767,23 @@
     \verinfo {QFooBar} {1.0 beta}
     \endcode
 
+    A special macro option, \e match, can be added for additional
+    regular expression pattern matching for expanded macros.
+
+    For example,
+
+    \badcode
+    macro.qtminorversion       = "$QT_VER"
+    macro.qtminorversion.match = "\\d+\\.(\\d+)"
+    \endcode
+
+    This creates a macro \\qtminorversion that expands to the minor
+    version based on the QT_VER environment variable.
+
+    A macro that defines a match pattern outputs all capture groups
+    (parentheses) concatenated together, or the exact matched string
+    if the pattern does not contain any capture groups.
+
     See also \l {alias-variable} {alias}.
 
     \target manifestmeta-variable