Add a new AST matcher 'optionally'.

This matcher matches any node and at the same time executes all its
inner matchers to produce any possbile result bindings.

This is useful when a user wants certain supplementary information
that's not always present along with the main match result.

1 files changed, 38 insertions, 12 deletions

diff --git a/clang/docs/LibASTMatchersReference.html b/clang/docs/LibASTMatchersReference.html
index 338399976f4..05562c543c4 100644
--- a/clang/docs/LibASTMatchersReference.html
+++ b/clang/docs/LibASTMatchersReference.html
@@ -4689,6 +4689,32 @@ Usable as: Any Matcher
 </pre></td></tr>
 
 
+<tr><td>Matcher&lt;*&gt;</td><td class="name" onclick="toggle('optionally0')"><a name="optionally0Anchor">optionally</a></td><td>Matcher&lt;*&gt;, ..., Matcher&lt;*&gt;</td></tr>
+<tr><td colspan="4" class="doc" id="optionally0"><pre>Matches any node regardless of the submatchers.
+
+However, optionally will generate a result binding for each matching
+submatcher.
+
+Useful when additional information which may or may not present about a
+main matching node is desired.
+
+For example, in:
+  class Foo {
+    int bar;
+  }
+The matcher:
+  cxxRecordDecl(
+    optionally(has(
+      fieldDecl(hasName("bar")).bind("var")
+  ))).bind("record")
+will produce a result binding for both "record" and "var".
+The matcher will produce a "record" binding for even if there is no data
+member named "bar" in that class.
+
+Usable as: Any Matcher
+</pre></td></tr>
+
+
 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1AbstractConditionalOperator.html">AbstractConditionalOperator</a>&gt;</td><td class="name" onclick="toggle('hasCondition5')"><a name="hasCondition5Anchor">hasCondition</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1Expr.html">Expr</a>&gt; InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasCondition5"><pre>Matches the condition expression of an if statement, for loop,
 switch statement or conditional operator.
@@ -5098,15 +5124,15 @@ with compoundStmt()
 <tr><td colspan="4" class="doc" id="hasInitStatement2"><pre>Matches selection statements with initializer.
 
 Given:
- void foo() { 
+ void foo() {
    if (int i = foobar(); i &gt; 0) {}
    switch (int i = foobar(); i) {}
-   for (auto&amp; a = get_range(); auto&amp; x : a) {} 
+   for (auto&amp; a = get_range(); auto&amp; x : a) {}
  }
- void bar() { 
+ void bar() {
    if (foobar() &gt; 0) {}
    switch (foobar()) {}
-   for (auto&amp; x : get_range()) {} 
+   for (auto&amp; x : get_range()) {}
  }
 ifStmt(hasInitStatement(anything()))
   matches the if statement in foo but not in bar.
@@ -6245,15 +6271,15 @@ Examples matches the if statement
 <tr><td colspan="4" class="doc" id="hasInitStatement0"><pre>Matches selection statements with initializer.
 
 Given:
- void foo() { 
+ void foo() {
    if (int i = foobar(); i &gt; 0) {}
    switch (int i = foobar(); i) {}
-   for (auto&amp; a = get_range(); auto&amp; x : a) {} 
+   for (auto&amp; a = get_range(); auto&amp; x : a) {}
  }
- void bar() { 
+ void bar() {
    if (foobar() &gt; 0) {}
    switch (foobar()) {}
-   for (auto&amp; x : get_range()) {} 
+   for (auto&amp; x : get_range()) {}
  }
 ifStmt(hasInitStatement(anything()))
   matches the if statement in foo but not in bar.
@@ -7005,15 +7031,15 @@ Example matches true (matcher = hasCondition(cxxBoolLiteral(equals(true))))
 <tr><td colspan="4" class="doc" id="hasInitStatement1"><pre>Matches selection statements with initializer.
 
 Given:
- void foo() { 
+ void foo() {
    if (int i = foobar(); i &gt; 0) {}
    switch (int i = foobar(); i) {}
-   for (auto&amp; a = get_range(); auto&amp; x : a) {} 
+   for (auto&amp; a = get_range(); auto&amp; x : a) {}
  }
- void bar() { 
+ void bar() {
    if (foobar() &gt; 0) {}
    switch (foobar()) {}
-   for (auto&amp; x : get_range()) {} 
+   for (auto&amp; x : get_range()) {}
  }
 ifStmt(hasInitStatement(anything()))
   matches the if statement in foo but not in bar.