[ast-matchers] Add hasSubstatement() traversal matcher for caseStmt(), defaultStmt(), labelStmt()

[LegalizeAdulthood]

Summary

Previously if you wanted to match the statement associated with
a case, default, or labelled statement, you had to use hasDescendant.
Review comments stated that hasDescendant is heavy-handed and that a
more specific traversal matcher was preferred. This is that
traversal matcher.

• Separate matcher definitions with a blank line.
• Add corresponding unit tests for new traversal matcher.
• Add the new matcher to the Registry
• Add documentation in the AST matchers reference HTML page.
• Remove trailing semi-colon from REGISTER_MATCHER macro to be consistent with the other macro declarations and fix a missing semi-colon in the invocation of the macro.

[LegalizeAdulthood]

I think while implementing this I got a little confused as to whether or not it was a narrowing or traversal matcher. It feels like a traversal matcher to me.

If someone would confirm my reasoning, I'd appreciate it. That means I should probably move the unit tests to the traversal tests file.

[LegalizeAdulthood]

Update based on comments from lint check

[LegalizeAdulthood]

Update to include labelStmt()
Move the unit tests to ASTMatchersTraversalTest.cpp

[LegalizeAdulthood]

Correct HTML copy/paste error for labelStmt() traversal

[LegalizeAdulthood]

clang-format

[LegalizeAdulthood]

clang/lib/ASTMatchers/Dynamic/Registry.cpp

358

I see there is another matcher called hasAnySubstatement where "substatement" is spelled out; I think I will rename this matcher hasSubstatement to be consistent with hasAnySubstatement.

[LegalizeAdulthood]

Rename hasSubstmt to hasSubstatement

[LegalizeAdulthood]

Document the new matcher in the clang release notes

[aaron.ballman]

Previously if you wanted to match the statement associated with a case, default, or labelled statement, you had to use hasDescendant.

This isn't true. You can use has() to do direct substatemematching, and I'm wondering whether we need this new matcher at all. e.g., https://godbolt.org/z/K5sYP757r

clang/include/clang/ASTMatchers/ASTMatchers.h

2432

Spurious newline?

7720

May need to reformat as well, but the intent is to make it clear that this does not behave like hasAnySubstatement().

7727

This is invalid code (there's nothing to break out of), so you may want to tweak the example a bit.

7730–7734

7737–7738

Pretty sure you can use the base class here as a simplification.

clang/lib/ASTMatchers/Dynamic/Registry.cpp

69

Good catch; feel free to land this and related changes as an NFC commit.

clang/unittests/ASTMatchers/ASTMatchersTraversalTest.cpp

161

Should fix the formatting.

[LegalizeAdulthood]

In D116328#3221995, @aaron.ballman wrote:

Previously if you wanted to match the statement associated with a case, default, or labelled statement, you had to use hasDescendant.

This isn't true. You can use has() to do direct substatemematching, and I'm wondering whether we need this new matcher at all. e.g., https://godbolt.org/z/K5sYP757r

Well, the whole point of this was that previous review comments were complaining that I was using an "expensive" matcher
instead of one that got right to the point. (What's the difference between has and hasDescendent anyway?)

I looked at the implementation of "has" and it has a huge amount of machinery underneath it. I drilled in as follows (my ToT hash is 773ab3c6655f4d2beec25bb3516b4d4fe2eea990):
ASTMatchers.h:3391 declares has as an instance of internal::ArgumentAdaptingMatcherFunc<internal::HasMatcher>
ArgumentAdaptingMatcherFun appears just to be a factory mechanism for creating the appropriate matcher.
HasMatcher seems to do the actual matching
HasMatcher<T, ChildT>::matches delegates to ASTMatchFinder::matchesChildOf(const T &Node, ...)
ASTMatchFinder::matchesChildOf(const T &Node, ...) delegates to another overload of matchesChildOf(const DynTypedNode &Node, ...)` after asserting a static type relationship (ASTMatchersInternal.h:762)
ASTMatchFinder::matchesChildOf(const DynTypedNode &Node, ...) is a virtual function with one implementation in MatchASTVisitor (ASTMatchFinder.cpp:659)
MatchASTVisitor::matchesChildOf delegates to memoizedMatchesRecursively (ASTMatchFinder.cpp:664)
For non-memoizable nodes, MatchASTVisitor::memoizedMatchesRecursively delegates to matchesRecursively (ASTMatchFinder.cpp:599)
MatchASTVIsitor::matchesRecursively instantiates a ASTNodeNotSpelledInSourceScope and a MatchChildASTVisitor upon which it calls findMatch (ASTMatchFinder.cpp:645)
MatchChildASTVisitor::findMatch does a series of DynNode.get<T> checks and delegates to the appropriate overload of MatchChildASTVisitor::traverse, in our case it would be the one for Stmt
MatchChildASTVisitor::traverse<T>(const T &Node) delegates to MatchChildASTVisitor::match<T>(const T &Node)
MatchChildASTVisitor::match<T>(const T &Node) instantiates a BoundNodesTreeBuilder and calls match on the held Matcher.

Honestly, at this point, I become lost in manually tracing the code through "go to definition" in my IDE. So I switched my unit test for HasCaseSubstmt to use has and drilled in through the debugger.
What I saw echoes the above, although I took the wrong branch in my manual analysis in memoizedMatchesRecursively, it goes down the memoization path.

However, the whole point of memoizing a result is because that result was expensive to compute and the memoization saves time on subsequent queries
because the result has been memorized. In this case, it's a simple getter on CaseStmt to obtain the node against which you want to match, so I don't
see the memoization as having any particular benefit. (The inner matcher to hasSubstatement may be expensive and could be memoized.) For results
obtain by the visitor pattern, I can see why you'd want to memoize them as there is lots of code being executed to implement the Visitor pattern.

clang/include/clang/ASTMatchers/ASTMatchers.h

2432

I didn't add this intentionally and I can remove it, but the general style in this file is to separate top-level decls by a blank line.

[aaron.ballman]

In D116328#3223268, @LegalizeAdulthood wrote:

In D116328#3221995, @aaron.ballman wrote:

Previously if you wanted to match the statement associated with a case, default, or labelled statement, you had to use hasDescendant.

This isn't true. You can use has() to do direct substatemematching, and I'm wondering whether we need this new matcher at all. e.g., https://godbolt.org/z/K5sYP757r

Well, the whole point of this was that previous review comments were complaining that I was using an "expensive" matcher
instead of one that got right to the point. (What's the difference between has and hasDescendent anyway?)

has() matches the direct descendant AST node, whereas hasDescendant() matches *any* descendant AST node. So hasDescendant() actually is expensive -- it can traverse the AST more times than you'd expect. I don't know of any performance concerns with has() though.

e.g., https://godbolt.org/z/n3adEz4qW (the first query matches nothing, the second query has a match)

I looked at the implementation of "has" and it has a huge amount of machinery underneath it. I drilled in as follows (my ToT hash is 773ab3c6655f4d2beec25bb3516b4d4fe2eea990):
ASTMatchers.h:3391 declares has as an instance of internal::ArgumentAdaptingMatcherFunc<internal::HasMatcher>
ArgumentAdaptingMatcherFun appears just to be a factory mechanism for creating the appropriate matcher.
HasMatcher seems to do the actual matching
HasMatcher<T, ChildT>::matches delegates to ASTMatchFinder::matchesChildOf(const T &Node, ...)
ASTMatchFinder::matchesChildOf(const T &Node, ...) delegates to another overload of matchesChildOf(const DynTypedNode &Node, ...)` after asserting a static type relationship (ASTMatchersInternal.h:762)
ASTMatchFinder::matchesChildOf(const DynTypedNode &Node, ...) is a virtual function with one implementation in MatchASTVisitor (ASTMatchFinder.cpp:659)
MatchASTVisitor::matchesChildOf delegates to memoizedMatchesRecursively (ASTMatchFinder.cpp:664)
For non-memoizable nodes, MatchASTVisitor::memoizedMatchesRecursively delegates to matchesRecursively (ASTMatchFinder.cpp:599)
MatchASTVIsitor::matchesRecursively instantiates a ASTNodeNotSpelledInSourceScope and a MatchChildASTVisitor upon which it calls findMatch (ASTMatchFinder.cpp:645)
MatchChildASTVisitor::findMatch does a series of DynNode.get<T> checks and delegates to the appropriate overload of MatchChildASTVisitor::traverse, in our case it would be the one for Stmt
MatchChildASTVisitor::traverse<T>(const T &Node) delegates to MatchChildASTVisitor::match<T>(const T &Node)
MatchChildASTVisitor::match<T>(const T &Node) instantiates a BoundNodesTreeBuilder and calls match on the held Matcher.

Honestly, at this point, I become lost in manually tracing the code through "go to definition" in my IDE.

I'm impressed you got this far -- the AST matching machinery under the hood is really quite complex! :-)

So I switched my unit test for HasCaseSubstmt to use has and drilled in through the debugger.
What I saw echoes the above, although I took the wrong branch in my manual analysis in memoizedMatchesRecursively, it goes down the memoization path.

Phew, that's good -- I would expect has to use the memoization pass.

However, the whole point of memoizing a result is because that result was expensive to compute and the memoization saves time on subsequent queries
because the result has been memorized. In this case, it's a simple getter on CaseStmt to obtain the node against which you want to match, so I don't
see the memoization as having any particular benefit. (The inner matcher to hasSubstatement may be expensive and could be memoized.) For results
obtain by the visitor pattern, I can see why you'd want to memoize them as there is lots of code being executed to implement the Visitor pattern.

My understanding (and my recollection here may be wrong) is that has() can memoize the results because the sub-matcher will always be matched against the immediate direct descendant AST node, but you can't get the same behavior from hasDescendant() or hasAncestor() because any of the descendant (or ancestor) nodes can be matched, so you have to traverse them instead of memoizing. I'm adding @sammccall in case he has information about the performance characteristics or thoughts about the proposed matcher in general.

[LegalizeAdulthood]

In D116328#3223299, @aaron.ballman wrote:

In D116328#3223268, @LegalizeAdulthood wrote:

In D116328#3221995, @aaron.ballman wrote:

has() matches the direct descendant AST node, whereas hasDescendant() matches *any* descendant AST node.
[...] I don't know of any performance concerns with has() though.

Thanks for the explanation!

Honestly, at this point, I become lost in manually tracing the code through "go to definition" in my IDE.

I'm impressed you got this far -- the AST matching machinery under the hood is really quite complex! :-)

Having CMake generate a VS project and drilling in with ReSharper for C++ is
pretty powerful :), but you have to manually keep track of how the template
and function arguments are being resolved in the dynamic execution. So it's
pretty easy to get lost in template oriented code, which is understandably
pretty common in AST land.

My understanding (and my recollection here may be wrong) is that has() can memoize the results
[...] but you can't get the same behavior from hasDescendant() or hasAncestor()

OK, that makes sense.

I'm adding @sammccall in case he has information about the performance characteristics or thoughts about
the proposed matcher in general.

So let me summarize what we've learned so far:

• has only descends one level, is memoizable, and is less expensive than hasDescendant
• has uses the Visitor pattern to compute the result that is memoized
• @sammccall might be aware of any performance related issues with has

My takeaway:

• if has isn't expensive, I can either ditch this public matcher or move it to be a private matcher used in my check

[LegalizeAdulthood]

Ping.

This review has been waiting for a week without any comment.

[aaron.ballman]

In D116328#3223344, @LegalizeAdulthood wrote:

My takeaway:

• if has isn't expensive, I can either ditch this public matcher or move it to be a private matcher used in my check

I don't think has() is particularly expensive, so I think you should be able to use it directly. However, if you profiled something and notice a measurable difference between has() and hasSubstatement() in practice, that would be really good for the community to know.

[LegalizeAdulthood]

In D116328#3241329, @aaron.ballman wrote:

In D116328#3223344, @LegalizeAdulthood wrote:

My takeaway:

• if has isn't expensive, I can either ditch this public matcher or move it to be a private matcher used in my check

[...] if you profiled something and notice a measurable difference
between has() and hasSubstatement() in practice, that would
be really good for the community to know.

Do we have some sort of benchmarking facility in place, or do I
have to homebrew something?

[aaron.ballman]

In D116328#3241486, @LegalizeAdulthood wrote:

In D116328#3241329, @aaron.ballman wrote:

In D116328#3223344, @LegalizeAdulthood wrote:

My takeaway:

• if has isn't expensive, I can either ditch this public matcher or move it to be a private matcher used in my check

[...] if you profiled something and notice a measurable difference
between has() and hasSubstatement() in practice, that would
be really good for the community to know.

Do we have some sort of benchmarking facility in place, or do I
have to homebrew something?

I've always homebrewed it, but if we have better facilities these days, I'd love to know about them!

[LegalizeAdulthood]

Abandoning this in favor of a private matcher where it is needed.

clang/docs/LibASTMatchersReference.html

 
 Given
   switch (1) { case 1: case 1+1: case 3 ... 4: ; }
 caseStmt(hasCaseConstant(integerLiteral()))
   matches "case 1:"
 </pre></td></tr>
 
 
+<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1CaseStmt.html">CaseStmt</a>&gt;</td><td class="name" onclick="toggle('hasSubstatement0')"><a name="hasSubstatement0Anchor">hasSubstatement</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt; InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasSubstatement0"><pre>Matches the substatement associated with a case statement.
+
+Given
+  switch (1) { case 1: break; case 2: return; break; default: return; break; }
+caseStmt(hasSubstatement(returnStmt()))
+  matches "case 2: return;"
+</pre></td></tr>
+
+
 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1CastExpr.html">CastExpr</a>&gt;</td><td class="name" onclick="toggle('hasSourceExpression0')"><a name="hasSourceExpression0Anchor">hasSourceExpression</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="hasSourceExpression0"><pre>Matches if the cast's source expression
 or opaque value's source expression matches the given matcher.
 
 Example 1: matches "a string"
 (matcher = castExpr(hasSourceExpression(cxxConstructExpr())))
 class URL { URL(string); };
 URL url = "a string";

 }
 The matcher:
   decompositionDecl(hasBinding(0,
   bindingDecl(hasName("f").bind("fBinding"))))
 matches the decomposition decl with 'f' bound to "fBinding".
 </pre></td></tr>
 
 
+<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1DefaultStmt.html">DefaultStmt</a>&gt;</td><td class="name" onclick="toggle('hasSubstatement1')"><a name="hasSubstatement1Anchor">hasSubstatement</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt; InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasSubstatement1"><pre>Matches the substatement associated with a default statement.
+
+Given
+  switch (1) { case 1: break; case 2: return; break; default: return; break; }
+defaultStmt(hasSubstatement(returnStmt()))
+  matches "default: return;"
+</pre></td></tr>
+
+
 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1DoStmt.html">DoStmt</a>&gt;</td><td class="name" onclick="toggle('hasBody0')"><a name="hasBody0Anchor">hasBody</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt; InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasBody0"><pre></pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1DoStmt.html">DoStmt</a>&gt;</td><td class="name" onclick="toggle('hasCondition3')"><a name="hasCondition3Anchor">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="hasCondition3"><pre>Matches the condition expression of an if statement, for loop,
 switch statement or conditional operator.
 
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_1LabelStmt.html">LabelStmt</a>&gt;</td><td class="name" onclick="toggle('hasSubstatement2')"><a name="hasSubstatement2Anchor">hasSubstatement</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt; InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="hasSubstatement2"><pre>Matches the substatement associated with a label statement.
+
+Given
+  foo: return;
+  bar: break;
+labelStmt(hasSubstatement(breakStmt()))
+  matches "bar: break;"
+</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('capturesVar0')"><a name="capturesVar0Anchor">capturesVar</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="capturesVar0"><pre>Matches a `LambdaCapture` that refers to the specified `VarDecl`. The
 `VarDecl` can be a separate variable that is captured by value or
 reference, or a synthesized variable if the capture has an initializer.
 
 Given
   void foo() {
     int x;

clang/docs/ReleaseNotes.rst

- The ``hasAnyCapture`` matcher now only accepts an inner matcher of type
   ``Matcher<LambdaCapture>``. The matcher originally accepted an inner matcher
   of type ``Matcher<CXXThisExpr>`` or ``Matcher<VarDecl>``.
 - The ``usingType`` matcher is now available and needed to refer to types that
   are referred to via using C++ using declarations.
   The associated ``UsingShadowDecl`` can be matched using ``throughUsingDecl``
   and the underlying ``Type`` with ``hasUnderlyingType``.
   ``hasDeclaration`` continues to see through the alias and apply to the
   underlying type.
+- The ``hasSubstatement`` matcher is now available and allows you to match the
+  statement associated with a labelled construct: case statement, default
+  statement or label statement.
 
 clang-format
 ------------
 
 - Option ``AllowShortEnumsOnASingleLine: false`` has been improved, it now
   correctly places the opening brace according to ``BraceWrapping.AfterEnum``.
 
 - Option ``QualifierAlignment`` has been added in order to auto-arrange the

clang/include/clang/ASTMatchers/ASTMatchers.h

 /// \endcode
 /// coawaitExpr()
 ///   matches 'co_await 1'
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, CoawaitExpr>
     coawaitExpr;
 /// Matches co_await expressions where the type of the promise is dependent
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, DependentCoawaitExpr>
     dependentCoawaitExpr;
+
 /// Matches co_yield expressions.
 ///
 /// Given
 /// \code
 ///   co_yield 1;
 /// \endcode
 /// coyieldExpr()
 ///   matches 'co_yield 1'

 AST_MATCHER_P(CaseStmt, hasCaseConstant, internal::Matcher<Expr>,
               InnerMatcher) {
   if (Node.getRHS())
     return false;
 
   return InnerMatcher.matches(*Node.getLHS(), Finder, Builder);
 }
 
+/// Matches the substatement associated with a case, default or label statement.
+///
+/// Given
+/// \code
+///   switch (1) { case 1: break; case 2: return; break; default: return; break;
+///   }
+///   foo: return;
+///   bar: break;
+/// \endcode
+///
+/// caseStmt(hasSubstmt(returnStmt()))
+///   matches "case 2: return;"
+/// defaultStmt(hasSubstmt(returnStmt()))
+///   matches "default: return;"
+/// labelStmt(hasSubstmt(breakStmt()))
+///   matches "bar: break;"
+AST_POLYMORPHIC_MATCHER_P(hasSubstatement,
+                          AST_POLYMORPHIC_SUPPORTED_TYPES(CaseStmt, DefaultStmt,
+                                                          LabelStmt),
+                          internal::Matcher<Stmt>, InnerMatcher) {
+  return InnerMatcher.matches(*Node.getSubStmt(), Finder, Builder);
+}
+
 /// Matches declaration that has a given attribute.
 ///
 /// Given
 /// \code
 ///   __attribute__((device)) void f() { ... }
 /// \endcode
 /// decl(hasAttr(clang::attr::CUDADevice)) matches the function declaration of
 /// f. If the matcher is used from clang-query, attr::Kind parameter should be

clang/lib/ASTMatchers/Dynamic/Registry.cpp

 void RegistryMaps::registerMatcher(
     StringRef MatcherName, std::unique_ptr<MatcherDescriptor> Callback) {
   assert(Constructors.find(MatcherName) == Constructors.end());
   Constructors[MatcherName] = std::move(Callback);
 }
 
 #define REGISTER_MATCHER(name)                                                 \
   registerMatcher(#name, internal::makeMatcherAutoMarshall(                    \
-                             ::clang::ast_matchers::name, #name));
+                             ::clang::ast_matchers::name, #name))
 
 #define REGISTER_MATCHER_OVERLOAD(name)                                        \
   registerMatcher(#name,                                                       \
       std::make_unique<internal::OverloadedMatcherDescriptor>(name##Callbacks))
 
 #define SPECIFIC_MATCHER_OVERLOAD(name, Id)                                    \
   static_cast<::clang::ast_matchers::name##_Type##Id>(                         \
       ::clang::ast_matchers::name)
RegistryMaps::RegistryMaps() {
   REGISTER_MATCHER(arraySubscriptExpr);
   REGISTER_MATCHER(arrayType);
   REGISTER_MATCHER(asString);
   REGISTER_MATCHER(asmStmt);
   REGISTER_MATCHER(atomicExpr);
   REGISTER_MATCHER(atomicType);
   REGISTER_MATCHER(attr);
   REGISTER_MATCHER(autoType);
-  REGISTER_MATCHER(autoreleasePoolStmt)
+  REGISTER_MATCHER(autoreleasePoolStmt);
   REGISTER_MATCHER(binaryConditionalOperator);
   REGISTER_MATCHER(binaryOperator);
   REGISTER_MATCHER(binaryOperation);
   REGISTER_MATCHER(bindingDecl);
   REGISTER_MATCHER(blockDecl);
   REGISTER_MATCHER(blockExpr);
   REGISTER_MATCHER(blockPointerType);
   REGISTER_MATCHER(booleanType);
RegistryMaps::RegistryMaps() {
   REGISTER_MATCHER(hasSelector);
   REGISTER_MATCHER(hasSingleDecl);
   REGISTER_MATCHER(hasSize);
   REGISTER_MATCHER(hasSizeExpr);
   REGISTER_MATCHER(hasSourceExpression);
   REGISTER_MATCHER(hasSpecializedTemplate);
   REGISTER_MATCHER(hasStaticStorageDuration);
   REGISTER_MATCHER(hasStructuredBlock);
+  REGISTER_MATCHER(hasSubstatement);
   REGISTER_MATCHER(hasSyntacticForm);
   REGISTER_MATCHER(hasTargetDecl);
   REGISTER_MATCHER(hasTemplateArgument);
   REGISTER_MATCHER(hasTemplateArgumentLoc);
   REGISTER_MATCHER(hasThen);
   REGISTER_MATCHER(hasThreadStorageDuration);
   REGISTER_MATCHER(hasTrailingReturn);
   REGISTER_MATCHER(hasTrueExpression);

clang/unittests/ASTMatchers/ASTMatchersTraversalTest.cpp

TEST(StatementMatcher, HasDescendant) {
   EXPECT_TRUE(matches(
     "class X; X *x(bool); bool b(int); void c() { int i; x(b(i)); }",
     HasDescendantVariableI));
   EXPECT_TRUE(notMatches(
     "class X; X *x(bool); bool b(int); void c() { int i; x(b(42)); }",
     HasDescendantVariableI));
 }
 
+TEST_P(ASTMatchersTest, HasCaseSubstmt) {
+  EXPECT_TRUE(matches(
+      "void f() { switch (1) { case 1: return; break; default: break; } }",
+      traverse(TK_AsIs, caseStmt(hasSubstatement(returnStmt())))));
+}
+
+TEST_P(ASTMatchersTest, HasDefaultSubstmt) {
+  EXPECT_TRUE(matches(
+      "void f() { switch (1) { case 1: return; break; default: break; } }",
+      traverse(TK_AsIs, defaultStmt(hasSubstatement(breakStmt())))));
+}
+
+TEST_P(ASTMatchersTest, HasLabelSubstmt) {
+  EXPECT_TRUE(matches("void f() { while (1) { bar: break; foo: return; } }",
+                      traverse(TK_AsIs, labelStmt(hasSubstatement(breakStmt())))));
+}
+
 TEST(TypeMatcher, MatchesClassType) {
   TypeMatcher TypeA = hasDeclaration(recordDecl(hasName("A")));
 
   EXPECT_TRUE(matches("class A { public: A *a; };", TypeA));
   EXPECT_TRUE(notMatches("class A {};", TypeA));
 
   TypeMatcher TypeDerivedFromA =
     hasDeclaration(cxxRecordDecl(isDerivedFrom("A")));