[ASTMatchers] Add a new matcher for callee declarations of Obj-C message expressions

[ziqingluo-90]

Summary

For an Obj-C message expression [o m], the adding matcher will match the declaration of the method m. This matcher is the Obj-C counterpart of the existing callee ASTMatcher which matches function/method declarations for C/C++ calls. So I think this matcher is general enough to be added to the ASTMatcher.h.

[njames93]

LGTM

[NoQ]

clang/include/clang/ASTMatchers/ASTMatchers.h

3841

Nitpick carryover: needs capital letter and .

[aaron.ballman]

clang/include/clang/ASTMatchers/ASTMatchers.h

3841

Don't forget to regen the docs when you fix this, too. :-)

3853

Is there a reason why we want a separate matcher here instead of overloading callee()?

[ziqingluo-90]

clang/include/clang/ASTMatchers/ASTMatchers.h

3853

This is a good question!

callee has already been overloaded to accept both Matcher<Decl> and Matcher<Stmt> as the parameter. In my case, I will need callee to be polymorphic in returning both Matcher<CallExpr> and Matcher<ObjCMessageExpr> types. So that will end up in 4 definitions of callee, one of which has different return type and parameter type from one of the others.

Is this achievable? I know I can overload parameters or make return types polymorphic, but can I mix them together?

[ziqingluo-90]

clang/include/clang/ASTMatchers/ASTMatchers.h

3853

I figured it out. I will soon update this patch to simply overload callee

[ziqingluo-90]

Taking @aaron.ballman 's advice to overload callee instead of creating a new matcher. Avoid to bloat ASTMatchers.h.

Sorry to the reviewers that have to review this patch again.

[aaron.ballman]

Thank you, this is looking really promising!

Can you also add a test to unittests/ASTMatchers/Dynamic/RegistryTest.cpp to the TEST_F(RegistryTest, OverloadedMatchers) test which tests the behavior of callee() to make sure it works from dynamic matchers? If that test fails, I think you may need to update lib/ASTMatchers/Dynamic/Registry.cpp to add a REGISTER_OVERLOADED_3 that is used by both callee and equals.

clang/include/clang/ASTMatchers/ASTMatchers.h

3891

This way you get an assert if someone adds another type and forgets to update the rest of the body.

[ziqingluo-90]

Added a test to unittests/ASTMatchers/Dynamic/RegistryTest.cpp and confirms that the overloaded callee still works with dynamic matchers

[aaron.ballman]

LGTM, thank you!

[ziqingluo-90]

Thanks @aaron.ballman , I plan to commit this patch on Monday (18th July 2022).

clang/docs/LibASTMatchersReference.html

 matcher = objCMessageExpr(hasReceiverType(asString("UIWebView *")));
 matches the [webView ...] message invocation.
   NSString *webViewJavaScript = ...
   UIWebView *webView = ...
   [webView stringByEvaluatingJavaScriptFromString:webViewJavascript];
 </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('objcMessageCallee0')"><a name="objcMessageCallee0Anchor">objcMessageCallee</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMethodDecl.html">ObjCMethodDecl</a>&gt; InnerMatcher</td></tr>
+<tr><td colspan="4" class="doc" id="objcMessageCallee0"><pre>matches if ObjCMessageExpr's callee declaration matches
+
+Given
+  @interface I: NSObject
+  +(void)foo;
+  @end
+  ...
+  [I foo]
+The example above matches [I foo] with
+objcMessageExpr(objcMessageCallee(objcMethodDecl(hasName("foo"))))
+</pre></td></tr>
+
+
 <tr><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1ObjCMethodDecl.html">ObjCMethodDecl</a>&gt;</td><td class="name" onclick="toggle('hasAnyParameter1')"><a name="hasAnyParameter1Anchor">hasAnyParameter</a></td><td>Matcher&lt;<a href="https://clang.llvm.org/doxygen/classclang_1_1ParmVarDecl.html">ParmVarDecl</a>&gt; InnerMatcher</td></tr>
 <tr><td colspan="4" class="doc" id="hasAnyParameter1"><pre>Matches any parameter of a function or an ObjC method declaration or a
 block.
 
 Does not match the 'this' parameter of a method.
 
 Given
   class X { void f(int x, int y, int z) {} };

clang/include/clang/ASTMatchers/ASTMatchers.h

 /// implemented in terms of implicit casts.
 AST_MATCHER_P(CallExpr, callee, internal::Matcher<Stmt>,
               InnerMatcher) {
   const Expr *ExprNode = Node.getCallee();
   return (ExprNode != nullptr &&
           InnerMatcher.matches(*ExprNode, Finder, Builder));
 }
 
+/// matches if ObjCMessageExpr's callee declaration matches
+///
+/// Given
+/// \code
+///   @interface I: NSObject
+///   +(void)foo;
+///   @end
+///   ...
+///   [I foo]
+/// \endcode
+/// The example above matches \code [I foo] \endcode with
+/// objcMessageExpr(objcMessageCallee(objcMethodDecl(hasName("foo"))))
+AST_MATCHER_P(ObjCMessageExpr, objcMessageCallee,
+              internal::Matcher<ObjCMethodDecl>, InnerMatcher) {
+  const ObjCMethodDecl *msgDecl = Node.getMethodDecl();
+  return (msgDecl != nullptr &&
+          InnerMatcher.matches(*msgDecl, Finder, Builder));
+}
+
 /// Matches if the call expression's callee's declaration matches the
 /// given matcher.
 ///
 /// Example matches y.x() (matcher = callExpr(callee(
 ///                                    cxxMethodDecl(hasName("x")))))
 /// \code
 ///   class Y { public: void x(); };
 ///   void z() { Y y; y.x(); }

 /// \code
 ///  class X {};
 ///  void y(X &x) { x; X z; }
 ///  typedef int U;
 ///  class Y { friend class X; };
 ///  class Z : public virtual X {};
 /// \endcode
 AST_POLYMORPHIC_MATCHER_P_OVERLOAD(
     hasType,
     AST_POLYMORPHIC_SUPPORTED_TYPES(Expr, FriendDecl, TypedefNameDecl,
                                     ValueDecl, CXXBaseSpecifier),
     internal::Matcher<QualType>, InnerMatcher, 0) {
   QualType QT = internal::getUnderlyingType(Node);
   if (!QT.isNull())
     return InnerMatcher.matches(QT, Finder, Builder);
   return false;
 }

clang/lib/ASTMatchers/Dynamic/Registry.cpp

RegistryMaps::RegistryMaps() {
   REGISTER_MATCHER(objcCategoryDecl);
   REGISTER_MATCHER(objcCategoryImplDecl);
   REGISTER_MATCHER(objcFinallyStmt);
   REGISTER_MATCHER(objcImplementationDecl);
   REGISTER_MATCHER(objcInterfaceDecl);
   REGISTER_MATCHER(objcIvarDecl);
   REGISTER_MATCHER(objcIvarRefExpr);
   REGISTER_MATCHER(objcMessageExpr);
+  REGISTER_MATCHER(objcMessageCallee);
   REGISTER_MATCHER(objcMethodDecl);
   REGISTER_MATCHER(objcObjectPointerType);
   REGISTER_MATCHER(objcPropertyDecl);
   REGISTER_MATCHER(objcProtocolDecl);
   REGISTER_MATCHER(objcStringLiteral);
   REGISTER_MATCHER(objcThrowStmt);
   REGISTER_MATCHER(objcTryStmt);
   REGISTER_MATCHER(ofClass);

clang/unittests/ASTMatchers/ASTMatchersNodeTest.cpp

EXPECT_TRUE(matchesObjC(Objc1String, objcMessageExpr(hasSelector("contents"),
                                                        hasUnarySelector())));
   EXPECT_TRUE(matchesObjC(Objc1String, objcMessageExpr(hasSelector("contents"),
                                                        numSelectorArgs(0))));
   EXPECT_TRUE(
       matchesObjC(Objc1String, objcMessageExpr(matchesSelector("uppercase*"),
                                                argumentCountIs(0))));
 }
 
+TEST(ASTMatchersTestObjC, ObjCMessageCallee) {
+  //  Will NOT match function callee:
+  EXPECT_TRUE(notMatchesObjC("void f() {"
+                             "  f(); "
+                             "}",
+                             objcMessageExpr(objcMessageCallee(hasName("f")))));
+
+  StringRef Objc1String = "@interface I "
+                          " - (void)instanceMethod;"
+                          " + (void)classMethod;"
+                          " + (void)uncalledMethod;"
+                          "@end\n"
+                          "int main(void) {\n"
+                          "  [I classMethod];"
+                          "  I *i = [[I alloc] init];"
+                          "  [i instanceMethod];"
+                          "}";
+  // Should find the two method declarations through the message expressions:
+  EXPECT_TRUE(
+      matchesObjC(Objc1String, objcMessageExpr(objcMessageCallee(
+                                   objcMethodDecl(hasName("classMethod"))))));
+  EXPECT_TRUE(matchesObjC(Objc1String,
+                          objcMessageExpr(objcMessageCallee(
+                              objcMethodDecl(hasName("instanceMethod"))))));
+  // Will NOT match a method declaration through `objcMessageCallee` if there is
+  // no such message expression:
+  EXPECT_FALSE(matchesObjC(Objc1String,
+                           objcMessageExpr(objcMessageCallee(
+                               objcMethodDecl(hasName("uncalledMethod"))))));
+}
+
 TEST(ASTMatchersTestObjC, ObjCStringLiteral) {
 
   StringRef Objc1String = "@interface NSObject "
                           "@end "
                           "@interface NSString "
                           "@end "
                           "@interface Test : NSObject "
                           "+ (void)someFunction:(NSString *)Desc; "