Add `LambdaCapture`-related matchers.

[jcking1034]

Summary

This provides better support for LambdaCaptures by making them first-
class and allowing them to be bindable. In addition, this implements several
LambdaCapture-related matchers. This does not update how lambdas are
traversed. As a result, something like trying to match lambdaCapture() by
itself will not work - it must be used as an inner matcher.

[aaron.ballman]

I'm a bit confused as to why this is necessary. We already have lambdaExpr(hasAnyCapture(varDecl(hasName("whatever")))) and lambdaExpr(hasAnyCapture(cxxThisExpr())), so I'm not certain why we need this as a parallel construct?

clang/include/clang/ASTMatchers/ASTMatchers.h

4629–4630

The name here is a bit unclear -- whether it is the matcher matching int x; or the x from the capture is not clear from the name. The comment suggests it's matching x from the capture, but I think it's actually matching the int x; variable declaration.

Being clear on what's matched here is important when we think about initializers:

void foo() {
  int x = 12;
  auto f = [x = 100](){};
}

and

lambdaExpr(hasAnyCapture(lambdaCapture(refersToVarDecl(hasName("x"), hasInitializer(integerLiteral(equals(100))))))

Would you expect this to match? (This might be a good test case to add.)

[ymandel]

Nice! Per Aaron's comment, it's probably worth expanding the patch description to explain the motivation. I assume that the key is making these first-class and therefore bindable?

clang/include/clang/ASTMatchers/ASTMatchFinder.h

170 ↗

(On Diff #382123)

Since top-level metching doesn't work, I think we *don't* want to add this overload.

225 ↗

(On Diff #382123)

i guess remove this too, if you remove the overload?

clang/include/clang/ASTMatchers/ASTMatchers.h

4595

4597–4605

Maybe add some more examples? e.g. demonstrating that you can match implicit captures seems valuable. For that same code snippet, maybe something like:

... lambdaCapture(refersToVarDecl(hasName("t")))

4629–4630

In a similar vein, do we want a separate matcher on the name of the capture itself? e.g. an overload of hasName? And what about matchers for the initializers? Those don't have to land in this patch, but do you think those would be doable?

[jcking1034]

Revert changes to ASTMatchFinder

[jcking1034]

Update comment with example

[jcking1034]

Update comments and tests

[jcking1034]

@aaron.ballman for the purpose of these matchers, what @ymandel said is correct - the goal is to allow LambdaCaptures themselves to be bindable.

clang/include/clang/ASTMatchers/ASTMatchers.h

4629–4630

I would expect @aaron.ballman's initializer example to match, and I added a similar test case to the one described. I think that if a capture does not have an initializer, then refersToVarDecl will match on the variable declaration before the lambda. However, if a capture does have an initializer, that initializer itself seems to be represented as a VarDecl in the AST, which is the VarDecl that gets matched.

For that reason, I think we may not need to have a separate matcher on the name of the capture itself. Additionally, since captures with/without initializers are both represented the same way, there may not be a good way to distinguish between them, so matchers for initializers may not be possible.

[aaron.ballman]

In D112491#3088363, @jcking1034 wrote:

@aaron.ballman for the purpose of these matchers, what @ymandel said is correct - the goal is to allow LambdaCaptures themselves to be bindable.

Should we be discussing deprecating the non-bindable matchers for lambda captures? I guess the part that worries me is there are now two ways to match the same sorts of constructs, and I'm a bit worried it won't be clear which one to reach for and when. Do you think this will be a usability concern for users?

clang/include/clang/ASTMatchers/ASTMatchers.h

4629–4630

I think that if a capture does not have an initializer, then refersToVarDecl will match on the variable declaration before the lambda. However, if a capture does have an initializer, that initializer itself seems to be represented as a VarDecl in the AST, which is the VarDecl that gets matched.

Oof, that'd be confusing! :-(

For that reason, I think we may not need to have a separate matcher on the name of the capture itself.

Er, but there are init captures where you can introduce a whole new declaration. I think we do want to be able to match on that, right? e.g.,

[x = 12](){ return x; }();

Additionally, since captures with/without initializers are both represented the same way, there may not be a good way to distinguish between them, so matchers for initializers may not be possible.

That's a bummer! :-( If this turns out to be a limitation, we should probably document it as such.

[jcking1034]

Update comment with additional example.

[jcking1034]

I agree that having two ways to match the same thing is a usability concern and could definitely be confusing. Deprecating non-bindable matchers could be a possibility and is probably the right way to go if we choose to include these matchers, but I'm not sure of if eventually removing these other matchers will have any side effects.

clang/include/clang/ASTMatchers/ASTMatchers.h

4629–4630

For the example you've provided, these can be matched with the refersToVarDecl matcher, as seen in the test LambdaCaptureTest_BindsToCaptureWithInitializer. I've gone ahead and updated the documentation to include an example with an initializer.

Having that limitation with initializer representation is definitely a concern, though. Looking through the source for the LambdaCapture class, the documentation for the DeclAndBits (line 42-48) suggests that there isn't a distinguishment between the two cases. However, do you think it's feasible to update the classes related to LambdaCapture obtain and store this information (possibly through updating the LambdaCaptureKind enum, updating the constructor/fields of the class, etc)?

[jcking1034]

Deprecate original overloads of hasAnyCapture.

[jcking1034]

Regenerate documentation.

[aaron.ballman]

In general, I'm happy with this. Adding @sammccall in case I've missed anything regarding the AST matcher internals or design concerns.

clang/include/clang/ASTMatchers/ASTMatchers.h

4629–4630

However, do you think it's feasible to update the classes related to LambdaCapture obtain and store this information (possibly through updating the LambdaCaptureKind enum, updating the constructor/fields of the class, etc)?

I think that would make sense (thought perhaps as an orthogonal patch). That we don't track init captures seems like a deficiency of the AST to me.

[sammccall]

This looks really sensible to me too. Some naming bikeshedding, but my main question is migration.

Supporting two things is indeed annoying and confusing. I agree it's not worth keeping the old way forever just to avoid writing refersToVarDecl.
The question is: how soon can we get rid of it? We should consider whether we can do it in this patch: just replace the old matcher with this one.

AFAICT the old matcher has no uses in-tree beyond tests/registration. FWIW it has no uses in our out-of-tree repo either (which generally is a heavy matchers user).
I'm sure it has users somewhere, but probably few, and the mechanical difficulty of updating them is low. Given that I think we should just break them, rather than deal with overloading and deprecation warnings and future cleanup just to put off breaking them for one more release cycle.

This is a tradeoff, to me it seems but reasonable people can disagree on the importance of stability. Aaron, happy to go with whatever you decide.

clang/include/clang/ASTMatchers/ASTMatchers.h

4632

I think capturesVar may be a clearer/more direct name.

For example given int y; [x(y)] { return x; } I would naively expect refersToVarDecl(hasName("y")) to match the capture.

4652

Again, why refersToThis rather than capturesThis, which is more specific and matches the AST?

[jcking1034]

Update matcher names for clarity.

[jcking1034]

clang/include/clang/ASTMatchers/ASTMatchers.h

4652

Initially, I think I saw that there were a few TemplateArgument matchers of the form refersToX, so I wanted to maintain some consistency with that. But I think I your suggestion makes things clearer, so will opt for that.

[aaron.ballman]

In D112491#3096935, @sammccall wrote:

This looks really sensible to me too. Some naming bikeshedding, but my main question is migration.

Supporting two things is indeed annoying and confusing. I agree it's not worth keeping the old way forever just to avoid writing refersToVarDecl.
The question is: how soon can we get rid of it? We should consider whether we can do it in this patch: just replace the old matcher with this one.

AFAICT the old matcher has no uses in-tree beyond tests/registration. FWIW it has no uses in our out-of-tree repo either (which generally is a heavy matchers user).
I'm sure it has users somewhere, but probably few, and the mechanical difficulty of updating them is low. Given that I think we should just break them, rather than deal with overloading and deprecation warnings and future cleanup just to put off breaking them for one more release cycle.

This is a tradeoff, to me it seems but reasonable people can disagree on the importance of stability. Aaron, happy to go with whatever you decide.

I did some looking around to see if I could find any uses of the matcher in the wild, and I can't spot any that aren't in a Clang fork. I think there's plenty of time for us to get feedback from early adopters if removing the old interface causes severe pain for anyone. So I'm on board with replacing the old APIs, but we should definitely have a release note explaining what's happening.

[ymandel]

+1 to removing the old versions of these matchers.

[ymandel]

clang/include/clang/ASTMatchers/ASTMatchers.h

4629–4630

Yeah, this seems orthogonal, if quite desirable. I imagine this will be a frustration in the future. :( But, fixing the AST itself seems like quite a lot of work.

4630–4632

update to new matcher name.

4650

clang/unittests/ASTMatchers/ASTMatchersNarrowingTest.cpp

4449

rename?

clang/unittests/ASTMatchers/ASTMatchersNodeTest.cpp

2248

and below as well.

[jcking1034]

Update missed names; remove original implementations of hasAnyCapture.

[fowles]

This is great!

clang/docs/LibASTMatchersReference.html

8394

I think this should be "matches x and x = 1

[sammccall]

Thanks for the changes, this looks great to me now.

clang/docs/LibASTMatchersReference.html

8394

either that or ... hasName("x") matches ...

Maybe it's worth explicitly saying in the doc text something like "this can be a separate variable captured by value or reference, or a synthesized variable if the capture has an initializer".

(There may end up being some confusion about the fact that these variables don't appear in AST dumps, but I don't think that's your problem to deal with here)

[jcking1034]

Update documentation for capturesVar matcher.

[jcking1034]

Rebase onto main.

[fowles]

Do we also want a forEachCapture matcher?

[aaron.ballman]

In D112491#3107361, @fowles wrote:

Do we also want a forEachCapture matcher?

That might be good follow-on work (I wouldn't insist on it for this patch though).

clang/docs/ReleaseNotes.rst

223–229 ↗

(On Diff #384578)

We should have an additional note about the removal of the old matchers.

[fowles]

In D112491#3108631, @aaron.ballman wrote:

That might be good follow-on work (I wouldn't insist on it for this patch though).

Completely agreed, just something that occurred to me as the next thing I will need when building on this.

[jcking1034]

Update release notes.

[jcking1034]

clang/docs/ReleaseNotes.rst

223–229 ↗

(On Diff #384578)

I believe that the only change made to the old matchers is that hasAnyCapture now accepts an inner matcher of type Matcher<LambdaCapture>, and no longer accepts inner matchers of type Matcher<CXXThisExpr> or Matcher<VarDecl>. I've revised this note and broken it up into two points for clarity.

[jcking1034]

@fowles @aaron.ballman I'll take a look at forEachCapture in the next patch. Also, I've discovered that the VarDecl node has a member function isInitCapture that seems like it could allow us to distinguish between captures with and without initializers (link) - I want to play around with that, as well.

[jcking1034]

@aaron.ballman Just wanted to confirm with you that the work here and release notes look good and can be wrapped up so that I can have @ymandel submit!

[aaron.ballman]

This continues to LGTM, thank you for it!

clang/docs/LibASTMatchersReference.html

 Note: this does not match declarations of member variables, which are
 "field" declarations in Clang parlance.
 
 Example matches a
   int a;
 </pre></td></tr>
 
 
+<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1LambdaCapture.html">LambdaCapture</a>&gt;</td><td class="name" onclick="toggle('lambdaCapture0')"><a name="lambdaCapture0Anchor">lambdaCapture</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1LambdaCapture.html">LambdaCapture</a>&gt;...</td></tr>
+<tr><td colspan="4" class="doc" id="lambdaCapture0"><pre></pre></td></tr>
+
+
 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>&gt;</td><td class="name" onclick="toggle('nestedNameSpecifierLoc0')"><a name="nestedNameSpecifierLoc0Anchor">nestedNameSpecifierLoc</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifierLoc.html">NestedNameSpecifierLoc</a>&gt;...</td></tr>
 <tr><td colspan="4" class="doc" id="nestedNameSpecifierLoc0"><pre>Same as nestedNameSpecifier but matches NestedNameSpecifierLoc.
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>&gt;</td><td class="name" onclick="toggle('nestedNameSpecifier0')"><a name="nestedNameSpecifier0Anchor">nestedNameSpecifier</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1NestedNameSpecifier.html">NestedNameSpecifier</a>&gt;...</td></tr>
 <tr><td colspan="4" class="doc" id="nestedNameSpecifier0"><pre>Matches nested name specifiers.
 

 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>&gt;</td><td class="name" onclick="toggle('equals13')"><a name="equals13Anchor">equals</a></td><td>double Value</td></tr>
 <tr><td colspan="4" class="doc" id="equals13"><pre></pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>&gt;</td><td class="name" onclick="toggle('equals9')"><a name="equals9Anchor">equals</a></td><td>unsigned Value</td></tr>
 <tr><td colspan="4" class="doc" id="equals9"><pre></pre></td></tr>
 
 
+<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1LambdaCapture.html">LambdaCapture</a>&gt;</td><td class="name" onclick="toggle('isImplicit2')"><a name="isImplicit2Anchor">isImplicit</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isImplicit2"><pre>Matches an entity that has been implicitly added by the compiler (e.g.
+implicit default/copy constructors).
+</pre></td></tr>
+
+
+<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1LambdaCapture.html">LambdaCapture</a>&gt;</td><td class="name" onclick="toggle('refersToThis0')"><a name="refersToThis0Anchor">refersToThis</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="refersToThis0"><pre>Matches a `LambdaCapture` that refers to 'this'.
+
+Given
+class C {
+  int cc;
+  int f() {
+    auto l = [this]() { return cc; };
+    return l();
+  }
+};
+lambdaExpr(hasAnyCapture(lambdaCapture(refersToThis())))
+  matches `[this]() { return cc; }`.
+</pre></td></tr>
+
+
+<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1LambdaExpr.html">LambdaExpr</a>&gt;</td><td class="name" onclick="toggle('hasAnyCapture0')"><a name="hasAnyCapture0Anchor">hasAnyCapture</a></td><td>LambdaCaptureMatcher InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasAnyCapture0"><pre>Matches any capture of a lambda expression.
+
+Given
+  void foo() {
+    int t = 5;
+    auto f = [=](){ return t; };
+  }
+lambdaExpr(hasAnyCapture(lambdaCapture()))
+  matches `[=](){ return t; }`.
+</pre></td></tr>
+
+
 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>&gt;</td><td class="name" onclick="toggle('isArrow0')"><a name="isArrow0Anchor">isArrow</a></td><td></td></tr>
 <tr><td colspan="4" class="doc" id="isArrow0"><pre>Matches member expressions that are called with '-&gt;' as opposed
 to '.'.
 
 Member calls on the implicit this pointer match as called with '-&gt;'.
 
 Given
   class Y {
Usable as: Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1AddrLabelExpr.html">AddrLabelExpr</a>&gt;, Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1CallExpr.html">CallExpr</a>&gt;,
   Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1EnumType.html">EnumType</a>&gt;, Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1InjectedClassNameType.html">InjectedClassNameType</a>&gt;, Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1LabelStmt.html">LabelStmt</a>&gt;,
   Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>&gt;, Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1QualType.html">QualType</a>&gt;, Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1RecordType.html">RecordType</a>&gt;,
   Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1TagType.html">TagType</a>&gt;, Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1TemplateSpecializationType.html">TemplateSpecializationType</a>&gt;,
   Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1TemplateTypeParmType.html">TemplateTypeParmType</a>&gt;, Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1TypedefType.html">TypedefType</a>&gt;,
   Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1UnresolvedUsingType.html">UnresolvedUsingType</a>&gt;
 </pre></td></tr>
 
 
-<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1LambdaExpr.html">LambdaExpr</a>&gt;</td><td class="name" onclick="toggle('hasAnyCapture1')"><a name="hasAnyCapture1Anchor">hasAnyCapture</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXThisExpr.html">CXXThisExpr</a>&gt; InnerMatcher</td></tr>
-<tr><td colspan="4" class="doc" id="hasAnyCapture1"><pre>Matches any capture of 'this' in a lambda expression.
+<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1LambdaCapture.html">LambdaCapture</a>&gt;</td><td class="name" onclick="toggle('refersToVarDecl0')"><a name="refersToVarDecl0Anchor">refersToVarDecl</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>&gt; InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="refersToVarDecl0"><pre>Matches a `LambdaCapture` that refers to the specified `VarDecl`
+
+Given
+  void foo() {
+    int x;
+    auto f = [x](){};
+  }
+lambdaExpr(hasAnyCapture(lambdaCapture(refersToVarDecl(hasName("x"))))
+  matches `[x](){}`.
+</pre></td></tr>
+
+
+<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1LambdaExpr.html">LambdaExpr</a>&gt;</td><td class="name" onclick="toggle('hasAnyCapture2')"><a name="hasAnyCapture2Anchor">hasAnyCapture</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1CXXThisExpr.html">CXXThisExpr</a>&gt; InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasAnyCapture2"><pre>Matches any capture of 'this' in a lambda expression.
 
 Given
   struct foo {
     void bar() {
       auto f = [this](){};
     }
   }
 lambdaExpr(hasAnyCapture(cxxThisExpr()))
   matches [this](){};
 </pre></td></tr>
 
 
-<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1LambdaExpr.html">LambdaExpr</a>&gt;</td><td class="name" onclick="toggle('hasAnyCapture0')"><a name="hasAnyCapture0Anchor">hasAnyCapture</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>&gt; InnerMatcher</td></tr>
-<tr><td colspan="4" class="doc" id="hasAnyCapture0"><pre>Matches any capture of a lambda expression.
+<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1LambdaExpr.html">LambdaExpr</a>&gt;</td><td class="name" onclick="toggle('hasAnyCapture1')"><a name="hasAnyCapture1Anchor">hasAnyCapture</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1VarDecl.html">VarDecl</a>&gt; InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasAnyCapture1"><pre>Matches any capture of a lambda expression.
 
 Given
   void foo() {
     int x;
     auto f = [x](){};
   }
 lambdaExpr(hasAnyCapture(anything()))
-  matches [x](){};
+  matches `[x](){}`.
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1MemberExpr.html">MemberExpr</a>&gt;</td><td class="name" onclick="toggle('hasDeclaration7')"><a name="hasDeclaration7Anchor">hasDeclaration</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>&gt;  InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasDeclaration7"><pre>Matches a node if the declaration associated with that node
 matches the given matcher.
 
 The associated declaration is:
 - for type nodes, the declaration of the underlying type
 - for CallExpr, the declaration of the callee

clang/include/clang/AST/ASTTypeTraits.h

 //
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_AST_ASTTYPETRAITS_H
 #define LLVM_CLANG_AST_ASTTYPETRAITS_H
 
 #include "clang/AST/ASTFwd.h"
 #include "clang/AST/DeclCXX.h"
+#include "clang/AST/LambdaCapture.h"
 #include "clang/AST/NestedNameSpecifier.h"
 #include "clang/AST/TemplateBase.h"
 #include "clang/AST/TypeLoc.h"
 #include "clang/Basic/LLVM.h"
 #include "llvm/ADT/DenseMapInfo.h"
 #include "llvm/Support/AlignOf.h"
 
 namespace llvm {
public:
   }
 
   /// \{
   /// Construct an identifier for the dynamic type of the node
   static ASTNodeKind getFromNode(const Decl &D);
   static ASTNodeKind getFromNode(const Stmt &S);
   static ASTNodeKind getFromNode(const Type &T);
   static ASTNodeKind getFromNode(const TypeLoc &T);
+  static ASTNodeKind getFromNode(const LambdaCapture &L);
   static ASTNodeKind getFromNode(const OMPClause &C);
   static ASTNodeKind getFromNode(const Attr &A);
   /// \}
 
   /// Returns \c true if \c this and \c Other represent the same kind.
   bool isSame(ASTNodeKind Other) const {
     return KindId != NKI_None && KindId == Other.KindId;
   }

 private:
   /// Kind ids.
   ///
   /// Includes all possible base and derived kinds.
   enum NodeKindId {
     NKI_None,
     NKI_TemplateArgument,
     NKI_TemplateArgumentLoc,
+    NKI_LambdaCapture,
     NKI_TemplateName,
     NKI_NestedNameSpecifierLoc,
     NKI_QualType,
 #define TYPELOC(CLASS, PARENT) NKI_##CLASS##TypeLoc,
 #include "clang/AST/TypeLocNodes.def"
     NKI_TypeLoc,
     NKI_LastKindWithoutPointerIdentity = NKI_TypeLoc,
     NKI_CXXBaseSpecifier,

 
 #define KIND_TO_KIND_ID(Class)                                                 \
   template <> struct ASTNodeKind::KindToKindId<Class> {                        \
     static const NodeKindId Id = NKI_##Class;                                  \
   };
 KIND_TO_KIND_ID(CXXCtorInitializer)
 KIND_TO_KIND_ID(TemplateArgument)
 KIND_TO_KIND_ID(TemplateArgumentLoc)
+KIND_TO_KIND_ID(LambdaCapture)
 KIND_TO_KIND_ID(TemplateName)
 KIND_TO_KIND_ID(NestedNameSpecifier)
 KIND_TO_KIND_ID(NestedNameSpecifierLoc)
 KIND_TO_KIND_ID(QualType)
 #define TYPELOC(CLASS, PARENT) KIND_TO_KIND_ID(CLASS##TypeLoc)
 #include "clang/AST/TypeLocNodes.def"
 KIND_TO_KIND_ID(TypeLoc)
 KIND_TO_KIND_ID(Decl)

 struct DynTypedNode::BaseConverter<
     TemplateArgument, void> : public ValueConverter<TemplateArgument> {};
 
 template <>
 struct DynTypedNode::BaseConverter<TemplateArgumentLoc, void>
     : public ValueConverter<TemplateArgumentLoc> {};
 
 template <>
+struct DynTypedNode::BaseConverter<LambdaCapture, void>
+    : public ValueConverter<LambdaCapture> {};
+
+template <>
 struct DynTypedNode::BaseConverter<
     TemplateName, void> : public ValueConverter<TemplateName> {};
 
 template <>
 struct DynTypedNode::BaseConverter<
     NestedNameSpecifierLoc,
     void> : public ValueConverter<NestedNameSpecifierLoc> {};
 

clang/include/clang/ASTMatchers/ASTMatchers.h

 using TypeMatcher = internal::Matcher<QualType>;
 using TypeLocMatcher = internal::Matcher<TypeLoc>;
 using NestedNameSpecifierMatcher = internal::Matcher<NestedNameSpecifier>;
 using NestedNameSpecifierLocMatcher = internal::Matcher<NestedNameSpecifierLoc>;
 using CXXBaseSpecifierMatcher = internal::Matcher<CXXBaseSpecifier>;
 using CXXCtorInitializerMatcher = internal::Matcher<CXXCtorInitializer>;
 using TemplateArgumentMatcher = internal::Matcher<TemplateArgument>;
 using TemplateArgumentLocMatcher = internal::Matcher<TemplateArgumentLoc>;
+using LambdaCaptureMatcher = internal::Matcher<LambdaCapture>;
 using AttrMatcher = internal::Matcher<Attr>;
 /// @}
 
 /// Matches any node.
 ///
 /// Useful when another matcher requires a child matcher, but there's no
 /// additional constraint. This will often be used with an explicit conversion
 /// to an \c internal::Matcher<> type such as \c TypeMatcher.
AST_MATCHER_P(ClassTemplateSpecializationDecl, hasSpecializedTemplate,
   const ClassTemplateDecl* Decl = Node.getSpecializedTemplate();
   return (Decl != nullptr &&
           InnerMatcher.matches(*Decl, Finder, Builder));
 }
 
 /// Matches an entity that has been implicitly added by the compiler (e.g.
 /// implicit default/copy constructors).
 AST_POLYMORPHIC_MATCHER(isImplicit,
-                        AST_POLYMORPHIC_SUPPORTED_TYPES(Decl, Attr)) {
+                        AST_POLYMORPHIC_SUPPORTED_TYPES(Decl, Attr,
+                                                        LambdaCapture)) {
   return Node.isImplicit();
 }
 
 /// Matches classTemplateSpecializations, templateSpecializationType and
 /// functionDecl that have at least one TemplateArgument matching the given
 /// InnerMatcher.
 ///
 /// Given
for (const Expr *Arg : Node.arguments()) {
     if (InnerMatcher.matches(*Arg, Finder, &Result)) {
       *Builder = std::move(Result);
       return true;
     }
   }
   return false;
 }
 
+extern const internal::VariadicAllOfMatcher<LambdaCapture> lambdaCapture;
+
+/// Matches any capture in a lambda expression.
+///
+/// Given
+/// \code
+///   void foo() {
+///     int t = 5;
+///     auto f = [=](){ return t; };
+///   }
+/// \endcode
+/// lambdaExpr(hasAnyCapture(lambdaCapture()))
+///   matches `[=](){ return t; }`.
+AST_MATCHER_P_OVERLOAD(LambdaExpr, hasAnyCapture, LambdaCaptureMatcher,
+                       InnerMatcher, 2) {
+  for (const LambdaCapture &Capture : Node.captures()) {
+    clang::ast_matchers::internal::BoundNodesTreeBuilder Result(*Builder);
+    if (InnerMatcher.matches(Capture, Finder, &Result)) {
+      *Builder = std::move(Result);
+      return true;
+    }
+  }
+  return false;
+}
+
+/// Matches a `LambdaCapture` that refers to the specified `VarDecl`
+///
+/// Given
+/// \code
+///   void foo() {
+///     int x;
+///     auto f = [x](){};
+///   }
+/// \endcode
+/// lambdaExpr(hasAnyCapture(lambdaCapture(refersToVarDecl(hasName("x"))))
+///   matches `[x](){}`.
+AST_MATCHER_P(LambdaCapture, refersToVarDecl, internal::Matcher<VarDecl>,
+              InnerMatcher) {
+  auto *capturedVar = Node.getCapturedVar();
+  return capturedVar && InnerMatcher.matches(*capturedVar, Finder, Builder);
+}
+
+/// Matches a `LambdaCapture` that refers to 'this'.
+///
+/// Given
+/// \code
+/// class C {
+///   int cc;
+///   int f() {
+///     auto l = [this]() { return cc; };
+///     return l();
+///   }
+/// };
+/// \endcode
+/// lambdaExpr(hasAnyCapture(lambdaCapture(refersToThis())))
+///   matches `[this]() { return cc; }`.
+AST_MATCHER(LambdaCapture, refersToThis) { return Node.capturesThis(); }
+
 /// Matches any capture of a lambda expression.
 ///
 /// Given
 /// \code
 ///   void foo() {
 ///     int x;
 ///     auto f = [x](){};
 ///   }
 /// \endcode
 /// lambdaExpr(hasAnyCapture(anything()))
-///   matches [x](){};
+///   matches `[x](){}`.
 AST_MATCHER_P_OVERLOAD(LambdaExpr, hasAnyCapture, internal::Matcher<VarDecl>,
                        InnerMatcher, 0) {
   for (const LambdaCapture &Capture : Node.captures()) {
     if (Capture.capturesVariable()) {
       BoundNodesTreeBuilder Result(*Builder);
       if (InnerMatcher.matches(*Capture.getCapturedVar(), Finder, &Result)) {
         *Builder = std::move(Result);
         return true;

clang/lib/AST/ASTTypeTraits.cpp

 #include "clang/AST/TypeLoc.h"
 
 using namespace clang;
 
 const ASTNodeKind::KindInfo ASTNodeKind::AllKindInfo[] = {
     {NKI_None, "<None>"},
     {NKI_None, "TemplateArgument"},
     {NKI_None, "TemplateArgumentLoc"},
+    {NKI_None, "LambdaCapture"},
     {NKI_None, "TemplateName"},
     {NKI_None, "NestedNameSpecifierLoc"},
     {NKI_None, "QualType"},
 #define TYPELOC(CLASS, PARENT) {NKI_##PARENT, #CLASS "TypeLoc"},
 #include "clang/AST/TypeLocNodes.def"
     {NKI_None, "TypeLoc"},
     {NKI_None, "CXXBaseSpecifier"},
     {NKI_None, "CXXCtorInitializer"},

clang/lib/ASTMatchers/Dynamic/Registry.cpp

RegistryMaps::RegistryMaps() {
   //
   // Other:
   // equalsNode
 
   registerMatcher("mapAnyOf",
                   std::make_unique<internal::MapAnyOfBuilderDescriptor>());
 
   REGISTER_OVERLOADED_2(callee);
-  REGISTER_OVERLOADED_2(hasAnyCapture);
   REGISTER_OVERLOADED_2(hasPrefix);
   REGISTER_OVERLOADED_2(hasType);
   REGISTER_OVERLOADED_2(ignoringParens);
   REGISTER_OVERLOADED_2(isDerivedFrom);
   REGISTER_OVERLOADED_2(isDirectlyDerivedFrom);
   REGISTER_OVERLOADED_2(isSameOrDerivedFrom);
   REGISTER_OVERLOADED_2(loc);
   REGISTER_OVERLOADED_2(pointsTo);
   REGISTER_OVERLOADED_2(references);
   REGISTER_OVERLOADED_2(thisPointerType);
 
   std::unique_ptr<MatcherDescriptor> equalsCallbacks[] = {
       MATCHER_OVERLOAD_ENTRY(equals, 0),
       MATCHER_OVERLOAD_ENTRY(equals, 1),
       MATCHER_OVERLOAD_ENTRY(equals, 2),
   };
   REGISTER_MATCHER_OVERLOAD(equals);
 
+  std::unique_ptr<MatcherDescriptor> hasAnyCaptureCallbacks[] = {
+      MATCHER_OVERLOAD_ENTRY(hasAnyCapture, 0),
+      MATCHER_OVERLOAD_ENTRY(hasAnyCapture, 1),
+      MATCHER_OVERLOAD_ENTRY(hasAnyCapture, 2),
+  };
+  REGISTER_MATCHER_OVERLOAD(hasAnyCapture);
+
   REGISTER_REGEX_MATCHER(isExpansionInFileMatching);
   REGISTER_REGEX_MATCHER(matchesName);
   REGISTER_REGEX_MATCHER(matchesSelector);
 
   REGISTER_MATCHER(accessSpecDecl);
   REGISTER_MATCHER(addrLabelExpr);
   REGISTER_MATCHER(alignOfExpr);
   REGISTER_MATCHER(allOf);
RegistryMaps::RegistryMaps() {
   REGISTER_MATCHER(isVirtual);
   REGISTER_MATCHER(isVirtualAsWritten);
   REGISTER_MATCHER(isVolatileQualified);
   REGISTER_MATCHER(isWeak);
   REGISTER_MATCHER(isWritten);
   REGISTER_MATCHER(lValueReferenceType);
   REGISTER_MATCHER(labelDecl);
   REGISTER_MATCHER(labelStmt);
+  REGISTER_MATCHER(lambdaCapture);
   REGISTER_MATCHER(lambdaExpr);
   REGISTER_MATCHER(linkageSpecDecl);
   REGISTER_MATCHER(materializeTemporaryExpr);
   REGISTER_MATCHER(member);
   REGISTER_MATCHER(memberExpr);
   REGISTER_MATCHER(memberHasSameNameAsBoundNode);
   REGISTER_MATCHER(memberPointerType);
   REGISTER_MATCHER(namedDecl);
RegistryMaps::RegistryMaps() {
   REGISTER_MATCHER(realFloatingPointType);
   REGISTER_MATCHER(recordDecl);
   REGISTER_MATCHER(recordType);
   REGISTER_MATCHER(referenceType);
   REGISTER_MATCHER(referenceTypeLoc);
   REGISTER_MATCHER(refersToDeclaration);
   REGISTER_MATCHER(refersToIntegralType);
   REGISTER_MATCHER(refersToTemplate);
+  REGISTER_MATCHER(refersToThis);
   REGISTER_MATCHER(refersToType);
+  REGISTER_MATCHER(refersToVarDecl);
   REGISTER_MATCHER(requiresZeroInitialization);
   REGISTER_MATCHER(returnStmt);
   REGISTER_MATCHER(returns);
   REGISTER_MATCHER(sizeOfExpr);
   REGISTER_MATCHER(specifiesNamespace);
   REGISTER_MATCHER(specifiesType);
   REGISTER_MATCHER(specifiesTypeLoc);
   REGISTER_MATCHER(statementCountIs);

clang/unittests/ASTMatchers/ASTMatchersNarrowingTest.cpp

EXPECT_TRUE(
       matches(Indirect, cxxRecordDecl(hasName("Derived"),
                                       hasDirectBase(hasType(cxxRecordDecl(
                                           hasName("Intermediate")))))));
   EXPECT_TRUE(notMatches(
       Indirect,
       cxxRecordDecl(hasName("Derived"),
                     hasDirectBase(hasType(cxxRecordDecl(hasName("Base")))))));
 }
+
+TEST_P(ASTMatchersTest, RefersToThis) {
+  if (!GetParam().isCXX11OrLater()) {
+    return;
+  }
+  auto matcher = lambdaExpr(hasAnyCapture(lambdaCapture(refersToThis())));
+  EXPECT_TRUE(matches("class C { int cc; int f() { auto l = [this](){ return "
+                      "cc; }; return l(); } };",
+                      matcher));
+  EXPECT_TRUE(matches("class C { int cc; int f() { auto l = [=](){ return cc; "
+                      "}; return l(); } };",
+                      matcher));
+  EXPECT_TRUE(matches("class C { int cc; int f() { auto l = [&](){ return cc; "
+                      "}; return l(); } };",
+                      matcher));
+  EXPECT_FALSE(matches("class C { int cc; int f() { auto l = [cc](){ return "
+                       "cc; }; return l(); } };",
+                       matcher));
+  EXPECT_FALSE(matches("class C { int this; int f() { auto l = [this](){ "
+                       "return this; }; return l(); } };",
+                       matcher));
+}
+
+TEST_P(ASTMatchersTest, IsImplicit_LambdaCapture) {
+  if (!GetParam().isCXX11OrLater()) {
+    return;
+  }
+  auto matcher = lambdaExpr(hasAnyCapture(
+      lambdaCapture(isImplicit(), refersToVarDecl(varDecl(hasName("cc"))))));
+  EXPECT_TRUE(
+      matches("int main() { int cc; auto f = [&](){ return cc; }; }", matcher));
+  EXPECT_TRUE(
+      matches("int main() { int cc; auto f = [=](){ return cc; }; }", matcher));
+  EXPECT_FALSE(matches("int main() { int cc; auto f = [cc](){ return cc; }; }",
+                       matcher));
+}
+
 } // namespace ast_matchers
 } // namespace clang

clang/unittests/ASTMatchers/ASTMatchersNodeTest.cpp

TEST_P(ASTMatchersTest,
   if (!GetParam().isCXX()) {
     return;
   }
   EXPECT_TRUE(
       notMatches("struct s {}; s ss;",
                  varDecl(hasName("ss"), hasTypeLoc(elaboratedTypeLoc()))));
 }
 
+TEST_P(ASTMatchersTest, LambdaCaptureTest) {
+  if (!GetParam().isCXX11OrLater()) {
+    return;
+  }
+  EXPECT_TRUE(matches("int main() { int cc; auto f = [cc](){ return cc; }; }",
+                      lambdaExpr(hasAnyCapture(lambdaCapture()))));
+}
+
+TEST_P(ASTMatchersTest, LambdaCaptureTest_BindsToCaptureReferringToVarDecl) {
+  if (!GetParam().isCXX11OrLater()) {
+    return;
+  }
+  auto matcher = lambdaExpr(
+      hasAnyCapture(lambdaCapture(refersToVarDecl(varDecl(hasName("cc"))))));
+  EXPECT_TRUE(matches("int main() { int cc; auto f = [cc](){ return cc; }; }",
+                      matcher));
+  EXPECT_TRUE(matches("int main() { int cc; auto f = [&cc](){ return cc; }; }",
+                      matcher));
+  EXPECT_TRUE(
+      matches("int main() { int cc; auto f = [=](){ return cc; }; }", matcher));
+  EXPECT_TRUE(
+      matches("int main() { int cc; auto f = [&](){ return cc; }; }", matcher));
+  if (!GetParam().isCXX14OrLater()) {
+    return;
+  }
+  EXPECT_TRUE(
+      matches("int main() { auto lambda = [cc = 1] {return cc;}; }", matcher));
+}
+
+TEST_P(ASTMatchersTest,
+       LambdaCaptureTest_DoesNotBindToCaptureReferringToVarDecl) {
+  if (!GetParam().isCXX11OrLater()) {
+    return;
+  }
+  auto matcher = lambdaExpr(
+      hasAnyCapture(lambdaCapture(refersToVarDecl(varDecl(hasName("cc"))))));
+  EXPECT_FALSE(matches("int main() { auto f = [](){ return 5; }; }", matcher));
+  EXPECT_FALSE(matches("int main() { int xx; auto f = [xx](){ return xx; }; }",
+                       matcher));
+  if (!GetParam().isCXX14OrLater()) {
+    return;
+  }
+  EXPECT_FALSE(
+      matches("int main() { auto lambda = [xx = 1] {return xx;}; }", matcher));
+}
+
 TEST(ASTMatchersTestObjC, ObjCMessageExpr) {
   // Don't find ObjCMessageExpr where none are present.
   EXPECT_TRUE(notMatchesObjC("", objcMessageExpr(anything())));
 
   StringRef Objc1String = "@interface Str "
                           " - (Str *)uppercaseString;"
                           "@end "
                           "@interface foo "