[ASTMatchers][OpenMP] OpenMP Structured-block-related matchers

[lebedev.ri]

Summary

Exposes the interface being added in D59214 for ASTMatchers.

[aaron.ballman]

include/clang/ASTMatchers/ASTMatchers.h

6421

What happens if this prereq is not met? Does the matcher return false, or does it do something worse (like assert)?

lib/ASTMatchers/Dynamic/Registry.cpp

513–515

Alphabetical order, please.

[lebedev.ri]

include/clang/ASTMatchers/ASTMatchers.h

6421

From https://reviews.llvm.org/D59214#change-5GOe7CiMwWxl

const Stmt *OMPExecutableDirective::getStructuredBlock() const {
  assert(!isStandaloneDirective() &&
         "Standalone Executable Directives don't have Structured Blocks.");

It really doesn't make sense to return false/nullptr,
it would be like trying to find ForLoop in VarDecl, they are just really distinct types.

[lebedev.ri]

include/clang/ASTMatchers/ASTMatchers.h

6421

Hmm, actually, i guess it would be best to return false here instead then. Will change.

[gribozavr]

include/clang/ASTMatchers/ASTMatchers.h

6389

"Matches standalone OpenMP directives, i.e., directives that can't have a structured block."

6400

Please follow the existing comment style. Either:

Given

\code
<code snippet>
\endcode

<matcher expression> matches "<code snippet>".

or

Example: <matcher expression> matches "<code snippet>" in 

\code
<code snippet>
\endcode
For example:

Given

 \code
   #pragma omp parallel default(none)
   #pragma omp parallel default(shared)
   #pragma omp parallel
 \endcode

``ompDefaultClause()`` matches ``default(none)` and ``default(shared)``.

Similarly for other comments in this patch.

[lebedev.ri]

Rebased, addressed all(?) nits.

[lebedev.ri]

@gribozavr thank you for the review!
@aaron.ballman any comments?

[aaron.ballman]

LGTM aside from a NFC change

include/clang/ASTMatchers/ASTMatchers.h

6436–6437

Rather than call the matcher (which is a heavy-handed solution), I'd prefer to just check Node.isOMPStructuredBlock() directly.

[lebedev.ri]

Last nit.

include/clang/ASTMatchers/ASTMatchers.h

6436–6437

Hmm, k.

docs/LibASTMatchersReference.html

 
 Given, `ompDefaultClause(isNoneKind())`:
 
   #pragma omp parallel default(none)   // <- match
   #pragma omp parallel default(shared) // <- no match
 </pre></td></tr>
 
 
+<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1OMPExecutableDirective.html">OMPExecutableDirective</a>&gt;</td><td class="name" onclick="toggle('isStandaloneDirective0')"><a name="isStandaloneDirective0Anchor">isStandaloneDirective</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isStandaloneDirective0"><pre>Given OpenMP directive, matches if it is an OpenMP standalone directive,
+i.e. an executable directive with no structured block.
+
+Example:
+
+Given ``ompExecutableDirective(isStandaloneDirective()))``:
+
+  #pragma omp parallel   // &lt;- no match, not standalone
+  {}
+  #pragma omp taskyield  // &lt;- match, is standalone
+</pre></td></tr>
+
+
 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMessageExpr.html">ObjCMessageExpr</a>&gt;</td><td class="name" onclick="toggle('argumentCountIs2')"><a name="argumentCountIs2Anchor">argumentCountIs</a></td><td>unsigned N</td></tr>
 <tr><td colspan="4" class="doc" id="argumentCountIs2"><pre>Checks that a call expression or a constructor call expression has
 a specific number of arguments (including absent default arguments).
 
 Example matches f(0, 0) (matcher = callExpr(argumentCountIs(2)))
   void f(int x, int y);
   f(0, 0);
 </pre></td></tr>
Example matches Y but not X
   class X {};
 SystemHeader.h:
   class Y {};
 
 Usable as: Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1Decl.html">Decl</a>&gt;, Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt;, Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1TypeLoc.html">TypeLoc</a>&gt;
 </pre></td></tr>
 
 
+<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1Stmt.html">Stmt</a>&gt;</td><td class="name" onclick="toggle('isOMPStructuredBlock0')"><a name="isOMPStructuredBlock0Anchor">isOMPStructuredBlock</a></td><td></td></tr>
+<tr><td colspan="4" class="doc" id="isOMPStructuredBlock0"><pre>Will match the Stmt AST node that is marked as being the structured block
+of an OpenMP executable directive.
+
+Example:
+
+Given ``stmt(isOMPStructuredBlock()))``:
+
+   #pragma omp parallel
+   ;                     // &lt;- will match `;`
+</pre></td></tr>
+
+
 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1StringLiteral.html">StringLiteral</a>&gt;</td><td class="name" onclick="toggle('hasSize1')"><a name="hasSize1Anchor">hasSize</a></td><td>unsigned N</td></tr>
 <tr><td colspan="4" class="doc" id="hasSize1"><pre>Matches nodes that have the specified size.
 
 Given
   int a[42];
   int b[2 * 21];
   int c[41], d[43];
   char *s = "abcd";

 
 Given ``ompExecutableDirective(hasClause(anything()))``:
 
   #pragma omp parallel               // &lt;- no clauses, no match
   #pragma omp parallel default(none) // &lt;- has clauses, match
 </pre></td></tr>
 
 
+<tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1OMPExecutableDirective.html">OMPExecutableDirective</a>&gt;</td><td class="name" onclick="toggle('hasStructuredBlock0')"><a name="hasStructuredBlock0Anchor">hasStructuredBlock</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="hasStructuredBlock0"><pre>Given OpenMP executable directive, matches if the InnerMatcher matches the
+structured block of this OpenMP executable directive.
+
+Prerequisite: the executable directive must not be standalone directive.
+
+Example:
+
+Given ``ompExecutableDirective(hasStructuredBlock(nullStmt()))``:
+
+   #pragma omp parallel
+   ;                     // &lt;- will match `;`
+
+   #pragma omp parallel
+   {}                    // &lt;- no match
+</pre></td></tr>
+
+
 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1OMPExecutableDirective.html">OMPExecutableDirective</a>&gt;</td><td class="name" onclick="toggle('isAllowedToContainClause0')"><a name="isAllowedToContainClause0Anchor">isAllowedToContainClause</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1OMPClause.html">OMPClause</a>&gt; ClauseMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="isAllowedToContainClause0"><pre>Matches if the OpenMP directive is allowed to contain the specified OpenMP
 clause kind.
 
 Example:
 
 Given,
   ``ompExecutableDirective(isAllowedToContainClause(ompDefaultClause()))``:

include/clang/ASTMatchers/ASTMatchers.h

 ///
 /// \code
 ///   #pragma omp parallel
 ///   #pragma omp for <...>
 /// \endcode
 extern const internal::VariadicDynCastAllOfMatcher<Stmt, OMPExecutableDirective>
     ompExecutableDirective;
 
+/// Given OpenMP directive, matches if it is an OpenMP standalone directive,
+/// i.e. an executable directive with no structured block.
+///
+/// Example:
+///
+/// Given ``ompExecutableDirective(isStandaloneDirective()))``:
+///
+/// \code
+///   #pragma omp parallel   // <- no match, not standalone
+///   {}
+///   #pragma omp taskyield  // <- match, is standalone
+/// \endcode
+AST_MATCHER(OMPExecutableDirective, isStandaloneDirective) {
+  return Node.isStandaloneDirective();
+}
+
+/// Will match the Stmt AST node that is marked as being the structured block
+/// of an OpenMP executable directive.
+///
+/// Example:
+///
+/// Given ``stmt(isOMPStructuredBlock()))``:
+///
+/// \code
+///    #pragma omp parallel
+///    ;                     // <- will match `;`
+/// \endcode
+AST_MATCHER(Stmt, isOMPStructuredBlock) { return Node.isOMPStructuredBlock(); }
+
+/// Given OpenMP executable directive, matches if the InnerMatcher matches the
+/// structured block of this OpenMP executable directive.
+///
+/// Prerequisite: the executable directive must not be standalone directive.
+///
+/// Example:
+///
+/// Given ``ompExecutableDirective(hasStructuredBlock(nullStmt()))``:
+///
+/// \code
+///    #pragma omp parallel
+///    ;                     // <- will match `;`
+/// \endcode
+///
+/// \code
+///    #pragma omp parallel
+///    {}                    // <- no match
+/// \endcode
+AST_MATCHER_P(OMPExecutableDirective, hasStructuredBlock,
+              internal::Matcher<Stmt>, InnerMatcher) {
+  return InnerMatcher.matches(*Node.getStructuredBlock(), Finder, Builder);
+}
+
 /// Given OpenMP directive, matches the first clause (out of all specified),
 /// that matches InnerMatcher.
 ///
 /// Example:
 ///
 /// Given ``ompExecutableDirective(hasClause(anything()))``:
 ///
 /// \code

lib/ASTMatchers/Dynamic/Registry.cpp

RegistryMaps::RegistryMaps() {
   REGISTER_MATCHER(voidType);
   REGISTER_MATCHER(whileStmt);
   REGISTER_MATCHER(withInitializer);
   REGISTER_MATCHER(ompExecutableDirective);
   REGISTER_MATCHER(hasClause);
   REGISTER_MATCHER(ompDefaultClause);
   REGISTER_MATCHER(isNoneKind);
   REGISTER_MATCHER(isAllowedToContainClause);
+  REGISTER_MATCHER(isStandaloneDirective);
+  REGISTER_MATCHER(isOMPStructuredBlock);
+  REGISTER_MATCHER(hasStructuredBlock);
 }
 
 RegistryMaps::~RegistryMaps() = default;
 
 static llvm::ManagedStatic<RegistryMaps> RegistryData;
 
 // static
 llvm::Optional<MatcherCtor> Registry::lookupMatcherCtor(StringRef MatcherName) {

unittests/ASTMatchers/ASTMatchersNarrowingTest.cpp

 TEST(Matcher, isMain) {
   EXPECT_TRUE(
     matches("int main() {}", functionDecl(isMain())));
 
   EXPECT_TRUE(
     notMatches("int main2() {}", functionDecl(isMain())));
 }
 
+TEST(OMPExecutableDirective, isStandaloneDirective) {
+  auto Matcher = ompExecutableDirective(isStandaloneDirective());
+
+  const std::string Source0 = R"(void x() {
+#pragma omp parallel
+;
+})";
+  EXPECT_TRUE(notMatchesWithOpenMP(Source0, Matcher));
+
+  const std::string Source1 = R"(void x() {
+#pragma omp taskyield
+})";
+  EXPECT_TRUE(matchesWithOpenMP(Source1, Matcher));
+}
+
+TEST(Stmt, isOMPStructuredBlock) {
+  const std::string Source0 = R"(void x() {
+#pragma omp parallel
+;
+})";
+  EXPECT_TRUE(
+      matchesWithOpenMP(Source0, stmt(nullStmt(), isOMPStructuredBlock())));
+
+  const std::string Source1 = R"(void x() {
+#pragma omp parallel
+{;}
+})";
+  EXPECT_TRUE(
+      notMatchesWithOpenMP(Source1, stmt(nullStmt(), isOMPStructuredBlock())));
+  EXPECT_TRUE(
+      matchesWithOpenMP(Source1, stmt(compoundStmt(), isOMPStructuredBlock())));
+}
+
+TEST(OMPExecutableDirective, hasStructuredBlock) {
+  const std::string Source0 = R"(void x() {
+#pragma omp parallel
+;
+})";
+  EXPECT_TRUE(matchesWithOpenMP(
+      Source0, ompExecutableDirective(hasStructuredBlock(nullStmt()))));
+
+  const std::string Source1 = R"(void x() {
+#pragma omp parallel
+{;}
+})";
+  EXPECT_TRUE(notMatchesWithOpenMP(
+      Source1, ompExecutableDirective(hasStructuredBlock(nullStmt()))));
+  EXPECT_TRUE(matchesWithOpenMP(
+      Source1, ompExecutableDirective(hasStructuredBlock(compoundStmt()))));
+}
+
 TEST(OMPExecutableDirective, hasClause) {
   auto Matcher = ompExecutableDirective(hasClause(anything()));
 
   const std::string Source0 = R"(void x() {
 ;
 })";
   EXPECT_TRUE(notMatchesWithOpenMP(Source0, Matcher));