Add `withIntrospection` matcher.

[jcking1034]

Summary

Adds a withIntrospection matcher which outputs contextual information for
better debugging. The format of the withIntrospection matcher's output is
open to debate.

This revision is intended for review, but also serves to demonstrate a use
case of the changes made in https://reviews.llvm.org/D113917, as these changes
allow for the withTag matcher to access the names of matchers.

[jcking1034]

Improve wrapping of PolymorphicMatchers

[jcking1034]

Change getMatcherName to getName

[jcking1034]

Chang withTag to withIntrospection

[avogelsgesang]

Nit:
Personally, I would prefer the name withDebugOutput over withIntrospection, as it more clearly describes the intent of this matcher.
At least to me, "introspection" is usually something done programatically, i.e. the matcher somehow reflects about its own state, but in this case all we are doing is printing some debug output to stderr.

Code looks good to me, but I don't know the LLVM coding guidelines and hence can't provide an actual code review

clang/include/clang/ASTMatchers/ASTMatchers.h

3000–3001

std::move(BeforeTag), std::move(AfterTag)

No need to create additional copies of those strings. Here and other places

[aaron.ballman]

In D113943#3184076, @avogelsgesang wrote:

Nit:
Personally, I would prefer the name withDebugOutput over withIntrospection, as it more clearly describes the intent of this matcher.
At least to me, "introspection" is usually something done programatically, i.e. the matcher somehow reflects about its own state, but in this case all we are doing is printing some debug output to stderr.

FWIW, I tend to agree that "introspection" is a bit of an odd choice for naming here. withDebugOutput would be an improvement, but withPrefixAndSuffix or something along those lines would also work.

clang/include/clang/ASTMatchers/ASTMatchers.h

3000–3001

Alternatively, it'd be great if we can switch these to use StringRef to avoid copies.

clang/include/clang/ASTMatchers/ASTMatchersInternal.h

1064–1066

All of those identifiers introduce UB because they're reserved, dropping the underscore solves the issue (and, oddly, matches our terrible coding style where we let ctor parameters shadow the names of member variables).

1784

clang/include/clang/ASTMatchers/ASTMatchers.h

 /// \code
 ///   namespace a { namespace b { class X; } }
 /// \endcode
 inline internal::Matcher<NamedDecl> hasName(StringRef Name) {
   return internal::Matcher<NamedDecl>(
       new internal::HasNameMatcher({std::string(Name)}));
 }
 
+template <typename T>
+inline internal::Matcher<T>
+withIntrospection(std::string BeforeTag, std::string AfterTag,
+                  const internal::Matcher<T> &InnerMatcher) {
+  return internal::Matcher<T>(new internal::WithIntrospectionMatcher<T>(
+      BeforeTag, AfterTag, InnerMatcher));
+}
+
+template <typename T, template <typename, typename... Params> class MatcherT,
+          typename ReturnTypesF, typename... ParamTypes>
+inline internal::PolymorphicWithIntrospectionMatcher<MatcherT, ReturnTypesF,
+                                                     ParamTypes...>
+withIntrospection(
+    std::string BeforeTag, std::string AfterTag,
+    const internal::PolymorphicMatcher<MatcherT, ReturnTypesF, ParamTypes...>
+        &InnerMatcher) {
+  return internal::PolymorphicWithIntrospectionMatcher<MatcherT, ReturnTypesF,
+                                                       ParamTypes...>(
+      BeforeTag, AfterTag, InnerMatcher);
+}
+
+template <typename T>
+inline internal::Matcher<T>
+withIntrospection(const internal::Matcher<T> &InnerMatcher) {
+  return internal::Matcher<T>(
+      new internal::WithIntrospectionMatcher<T>(InnerMatcher));
+}
+
+template <template <typename, typename... Params> class MatcherT,
+          typename ReturnTypesF, typename... ParamTypes>
+inline internal::PolymorphicWithIntrospectionMatcher<MatcherT, ReturnTypesF,
+                                                     ParamTypes...>
+withIntrospection(
+    const internal::PolymorphicMatcher<MatcherT, ReturnTypesF, ParamTypes...>
+        &InnerMatcher) {
+  return internal::PolymorphicWithIntrospectionMatcher<MatcherT, ReturnTypesF,
+                                                       ParamTypes...>(
+      InnerMatcher);
+}
+
 /// Matches NamedDecl nodes that have any of the specified names.
 ///
 /// This matcher is only provided as a performance optimization of hasName.
 /// \code
 ///     hasAnyName(a, b, c)
 /// \endcode
 ///  is equivalent to, but faster than
 /// \code

clang/include/clang/ASTMatchers/ASTMatchersInternal.h

 #include "clang/AST/Decl.h"
 #include "clang/AST/DeclCXX.h"
 #include "clang/AST/DeclFriend.h"
 #include "clang/AST/DeclTemplate.h"
 #include "clang/AST/Expr.h"
 #include "clang/AST/ExprCXX.h"
 #include "clang/AST/ExprObjC.h"
 #include "clang/AST/NestedNameSpecifier.h"
+#include "clang/AST/PrettyPrinter.h"
 #include "clang/AST/Stmt.h"
 #include "clang/AST/TemplateName.h"
 #include "clang/AST/Type.h"
 #include "clang/AST/TypeLoc.h"
 #include "clang/Basic/LLVM.h"
 #include "clang/Basic/OperatorKinds.h"
 #include "llvm/ADT/APFloat.h"
 #include "llvm/ADT/ArrayRef.h"
bool matchesSpecialized(const FunctionDecl &Node) const {
     return Node.isOverloadedOperator() &&
            llvm::is_contained(
                Names, getOperatorSpelling(Node.getOverloadedOperator()));
   }
 
   std::vector<std::string> Names;
 };
 
+template <typename T>
+class WithIntrospectionMatcher : public MatcherInterface<T> {
+public:
+  explicit WithIntrospectionMatcher(std::string _BeforeTag,
+                                    std::string _AfterTag,
+                                    internal::Matcher<T> _InnerMatcher)
+      : BeforeTag(std::move(_BeforeTag)), AfterTag(std::move(_AfterTag)),
+        InnerMatcher(_InnerMatcher) {}
+  explicit WithIntrospectionMatcher(internal::Matcher<T> _InnerMatcher)
+      : BeforeTag("⭐ Attempting new match"),
+        AfterTag("✔️ Concluding attempt"), InnerMatcher(_InnerMatcher) {}
+  bool matches(const T &Node, ASTMatchFinder *Finder,
+               BoundNodesTreeBuilder *Builder) const override {
+    DynTypedNode DTN = DynTypedNode::create(Node);
+
+    llvm::errs() << BeforeTag << "\n";
+
+    llvm::errs() << "Matcher Name: " << InnerMatcher.getName() << "\n";
+
+    llvm::errs() << "Node Kind: " << DTN.getNodeKind().asStringRef() << "\n"
+                 << "Node Value:\n```\n";
+    DTN.print(llvm::errs(), PrintingPolicy(LangOptions()));
+    llvm::errs() << "\n```\n"
+                 << "Node AST:\n";
+    DTN.dump(llvm::errs(), Finder->getASTContext());
+
+    bool result = InnerMatcher.matches(Node, Finder, Builder);
+    llvm::errs() << "Result: " << (result ? "Successful\n" : "Unsuccessful\n");
+
+    llvm::errs() << AfterTag << "\n\n";
+
+    return result;
+  }
+
+private:
+  std::string BeforeTag;
+  std::string AfterTag;
+  internal::Matcher<T> InnerMatcher;
+};
+
 /// Matches named declarations with a specific name.
 ///
 /// See \c hasName() and \c hasAnyName() in ASTMatchers.h for details.
 class HasNameMatcher : public SingleNodeMatcherInterface<NamedDecl> {
  public:
   explicit HasNameMatcher(std::vector<std::string> Names);
 
   bool matchesNode(const NamedDecl &Node) const override;
return Matcher<T>(
         new_from_tuple<MatcherT<T, ParamTypes...>>(std::move(Params)));
   }
 #endif
 
 private:
   std::tuple<ParamTypes...> Params;
 };
 
+template <template <typename T, typename... Params> class MatcherT,
+          typename ReturnTypesF, typename... ParamTypes>
+class PolymorphicWithIntrospectionMatcher {
+public:
+  PolymorphicWithIntrospectionMatcher(
+      internal::PolymorphicMatcher<MatcherT, ReturnTypesF, ParamTypes...>
+          _InnerMatcher)
+      : InnerMatcher(_InnerMatcher) {}
+
+  using ReturnTypes = typename ExtractFunctionArgMeta<ReturnTypesF>::type;
+
+  template <typename T> operator Matcher<T>() const LLVM_LVALUE_FUNCTION {
+    static_assert(TypeListContainsSuperOf<ReturnTypes, T>::value,
+                  "right polymorphic conversion");
+    return internal::Matcher<T>(new internal::WithIntrospectionMatcher<T>(
+        internal::Matcher<T>(InnerMatcher)));
+  }
+
+#if LLVM_HAS_RVALUE_REFERENCE_THIS
+  template <typename T> operator Matcher<T>() && {
+    static_assert(TypeListContainsSuperOf<ReturnTypes, T>::value,
+                  "right polymorphic conversion");
+    return internal::Matcher<T>(new internal::WithIntrospectionMatcher<T>(
+        internal::Matcher<T>(std::move(InnerMatcher))));
+  }
+#endif
+
+private:
+  internal::PolymorphicMatcher<MatcherT, ReturnTypesF, ParamTypes...>
+      InnerMatcher;
+};
+
 /// Matches nodes of type T that have child nodes of type ChildT for
 /// which a specified child matcher matches.
 ///
 /// ChildT must be an AST base type.
 template <typename T, typename ChildT>
 class HasMatcher : public MatcherInterface<T> {
   DynTypedMatcher InnerMatcher;