Add infrastructure to support matcher names.

[jcking1034]

Summary

This contains changes to the AST Matcher infrastructure in order to provide
contextual information about each matcher. This information can be useful for
tasks such as performing introspection on matchers.

One example which demonstrates the value of such changes can be seen in
https://reviews.llvm.org/D113943, which allows for the introspection of
matchers to improve the process of debugging matchers.

[jcking1034]

clang/include/clang/ASTMatchers/ASTMatchersInternal.h

1038

Here and below, we have the option to use the name of the matcher (for this, we could use "hasOverloadedOperatorName" instead). However, some of these classes are used in multiple matchers. For example, HasOverloadedOperatorNameMatcher is used in both hasOverloadedOperatorName and hasAnyOverloadedOperatorName, which I'm a bit concerned about.

1426

@ymandel suggested an alternate implementation where we instead pass the matcher name to makeAllOfComposite, which then passes the name to constructVariadic, to avoid making changes to BindableMatcher. I may look into this again, but my previous attempts to try this approach seemed messy due to the fact that these functions are used in a few different places, and because makeAllOfComposite handles cases with 0 or 1 inner matchers without constructing a variadic matcher.

[ymandel]

For a little more context: we're working to improve the debuggability of matchers. The first step in that direction seems to be a change of this sort that provides some (dynamic) introspection so that a tool, library, etc. can see some basic information about the matcher.

note that this leaves a fair amount of room for different design decisions. Of all those that we've considered, the most relevant seems to be using an enum for the result of getName (that is, the introspection method). We chose a string so as to easily accomodate user-defined matchers, both those defined with the macros and otherwise. However, we are open to different proposals.

In addition, James is preparing a follow up patch with a new matcher that exploits this functionality to create detailed matcher logging, which is really helpful for debugging matchers during development.

[jcking1034]

Add tests, rename getMatcherName to getName, update makeAllOfComposite

[jcking1034]

clang/include/clang/ASTMatchers/ASTMatchersInternal.h

1426

Following up on this, I've gone ahead and implemented @ymandel 's approach, as the original implementation led to some issues with getName returning the wrong name.

[ymandel]

Looks good, just small comments.

clang/include/clang/ASTMatchers/ASTMatchersInternal.h

88

Please note in the comments that this function template is specialized below to cover most (all) of the AST. So, the default string here should only very rarely (never?) be used.

449

As a pure virtual method, this is defining an API. Please add a comment that explains to users and implementors any expecations/requirements on this method.

1039

here and below: drop the "Matcher" suffix?

1389–1390

here and line 1381: maybe replace "return" with "wrap"? The existing comment is wrong as is and feels even more off with this change.

[jcking1034]

Update comments, drop "Matcher" suffix from getNames

[jcking1034]

clang/include/clang/ASTMatchers/ASTMatchersInternal.h

1039

Done. I've realized that this is a separate issue, but I'm still somewhat concerned about how the HasOverloadedOperatorNameMatcher is used in two different matchers, such that both hasOverloadedOperatorName and hasAnyOverloadedOperatorName will both have the name "HasOverloadedOperatorName".

[hokein]

The approach looks fine in general, just some nits when reading through the patch.

clang/include/clang/ASTMatchers/ASTMatchersInternal.h

152

These are types that are not covered in the above gen .inc files. I wonder is there a way to verify this list is complete?

clang/lib/ASTMatchers/ASTMatchersInternal.cpp

120

std::move(MatcherName), and elsewhere.

165

_MatcherName => MatcherName

308

std::move(MatcherName)

[jcking1034]

Address comments.

[jcking1034]

clang/include/clang/ASTMatchers/ASTMatchersInternal.h

152

I compared this list to other portions of the code where a similar pattern was used, and have just added specializations for OMP-related nodes. In these other portions of code, I didn't notice anything that verifies completeness, but I agree that this would be preferable.

[jcking1034]

@hokein @aaron.ballman Following up on this, let me know if there are any other action items to address!

[aaron.ballman]

clang/include/clang/ASTMatchers/ASTMatchersInternal.h

88

Should we be asserting that we never use it so that we can have 100% coverage up front and rely on the assertion to catch later issues?

90

Does the return type need to be std::string instead of StringRef? It looks like everything is returning a string literal.

578

Is there a need for this to accept a std::string as opposed to StringRef?

clang/lib/ASTMatchers/ASTMatchersInternal.cpp

131

FWIW, this is the only place I was expecting to see a std::string (places where it's needed for long-term storage).

[ymandel]

Aaron - agreed on the points about StringRef vs std::string. But, before I make that change, what did you think of moving to a more general method getMatcherSpec that returns an object? That object will provide the name (for now) and other data in the future (like the enum we discussed in the RFC thread)?

[aaron.ballman]

In D113917#3193374, @ymandel wrote:

Aaron - agreed on the points about StringRef vs std::string. But, before I make that change, what did you think of moving to a more general method getMatcherSpec that returns an object? That object will provide the name (for now) and other data in the future (like the enum we discussed in the RFC thread)?

I think that's a reasonable approach!

clang/include/clang/ASTMatchers/ASTMatchersInternal.h

 class ASTContext;
 
 namespace ast_matchers {
 
 class BoundNodes;
 
 namespace internal {
 
+/// Helper function that obtains a name for a matcher based on its type, which
+/// can be useful for cases like debugging matchers. This function template is
+/// specialized below to cover most of the AST, so the default string returned
+/// here should rarely be used.
+template <typename T> std::string makeMatcherNameFromType() {
+  return "Matcher<T>";
+}
+
+#define TYPELOC(CLASS, PARENT)                                                 \
+  template <> inline std::string makeMatcherNameFromType<CLASS##TypeLoc>() {   \
+    return "`" #CLASS "TypeLoc` Node";                                         \
+  }
+#define ABSTRACT_TYPELOC(CLASS, PARENT)
+#include "clang/AST/TypeLocNodes.def"
+
+template <> inline std::string makeMatcherNameFromType<TypeLoc>() {
+  return "`TypeLoc` Node";
+}
+
+#define DECL(CLASS, PARENT)                                                    \
+  template <> inline std::string makeMatcherNameFromType<CLASS##Decl>() {      \
+    return "`" #CLASS "Decl` Node";                                            \
+  }
+#define ABSTRACT_DECL(CLASS)
+#include "clang/AST/DeclNodes.inc"
+
+template <> inline std::string makeMatcherNameFromType<Decl>() {
+  return "`Decl` Node";
+}
+
+#define STMT(CLASS, PARENT)                                                    \
+  template <> inline std::string makeMatcherNameFromType<CLASS>() {            \
+    return "`" #CLASS "` Node";                                                \
+  }
+#define ABSTRACT_STMT(CLASS)
+#include "clang/AST/StmtNodes.inc"
+
+template <> inline std::string makeMatcherNameFromType<Stmt>() {
+  return "`Stmt` Node";
+}
+
+#define TYPE(CLASS, PARENT)                                                    \
+  template <> inline std::string makeMatcherNameFromType<CLASS##Type>() {      \
+    return "`" #CLASS "Type` Node";                                            \
+  }
+#define ABSTRACT_TYPE(CLASS, PARENT)
+#include "clang/AST/TypeNodes.inc"
+
+template <> inline std::string makeMatcherNameFromType<Type>() {
+  return "`Type` Node";
+}
+
+#define CLAUSE_CLASS(ENUM, STR, CLASS)                                         \
+  template <> inline std::string makeMatcherNameFromType<CLASS>() {            \
+    return "`" #CLASS "` Node";                                                \
+  }
+#define GEN_CLANG_CLAUSE_CLASS
+#include "llvm/Frontend/OpenMP/OMP.inc"
+
+template <> inline std::string makeMatcherNameFromType<OMPClause>() {
+  return "`OMPClause` Node";
+}
+
+#define ATTR(A)                                                                \
+  template <> inline std::string makeMatcherNameFromType<A##Attr>() {          \
+    return "`" #A "Attr` Node";                                                \
+  }
+#include "clang/Basic/AttrList.inc"
+
+template <> inline std::string makeMatcherNameFromType<Attr>() {
+  return "`Attr` Node";
+}
+
+#define MAKE_MATCHER_NAME_FROM_TYPE(CLASS)                                     \
+  template <> inline std::string makeMatcherNameFromType<CLASS>() {            \
+    return "`" #CLASS "` Node";                                                \
+  }
+MAKE_MATCHER_NAME_FROM_TYPE(TemplateArgument)
+MAKE_MATCHER_NAME_FROM_TYPE(TemplateArgumentLoc)
+MAKE_MATCHER_NAME_FROM_TYPE(TemplateName)
+MAKE_MATCHER_NAME_FROM_TYPE(NestedNameSpecifier)
+MAKE_MATCHER_NAME_FROM_TYPE(NestedNameSpecifierLoc)
+MAKE_MATCHER_NAME_FROM_TYPE(QualType)
+MAKE_MATCHER_NAME_FROM_TYPE(CXXBaseSpecifier)
+MAKE_MATCHER_NAME_FROM_TYPE(CXXCtorInitializer)
+MAKE_MATCHER_NAME_FROM_TYPE(LambdaCapture)
+#undef MAKE_MATCHER_NAME_FROM_TYPE
+
 /// A type-list implementation.
 ///
 /// A "linked list" of types, accessible by using the ::head and ::tail
 /// typedefs.
 template <typename... Ts> struct TypeList {}; // Empty sentinel type list.
 
 template <typename T1, typename... Ts> struct TypeList<T1, Ts...> {
   /// The first type on the list.
public:
   /// May bind \p DynNode to an ID via \p Builder, or recurse into
   /// the AST via \p Finder.
   virtual bool dynMatches(const DynTypedNode &DynNode, ASTMatchFinder *Finder,
                           BoundNodesTreeBuilder *Builder) const = 0;
 
   virtual llvm::Optional<clang::TraversalKind> TraversalKind() const {
     return llvm::None;
   }
+
+  /// Returns a name relevant to the interface.
+  ///
+  /// The name returned should be specific to the interface, such that it can
+  /// be used to identify said interface.
+  virtual std::string getName() const = 0;
 };
 
 /// Generic interface for matchers on an AST node of type T.
 ///
 /// Implement this if your matcher may need to inspect the children or
 /// descendants of the node or bind matched nodes to names. If you are
 /// writing a simple matcher that only inspects properties of the
 /// current node and doesn't care about its children or descendants,
 /// implement SingleNodeMatcherInterface instead.
 template <typename T>
 class MatcherInterface : public DynMatcherInterface {
 public:
   /// Returns true if 'Node' can be matched.
   ///
   /// May bind 'Node' to an ID via 'Builder', or recurse into
   /// the AST via 'Finder'.
   virtual bool matches(const T &Node,
                        ASTMatchFinder *Finder,
                        BoundNodesTreeBuilder *Builder) const = 0;
 
   bool dynMatches(const DynTypedNode &DynNode, ASTMatchFinder *Finder,
                   BoundNodesTreeBuilder *Builder) const override {
     return matches(DynNode.getUnchecked<T>(), Finder, Builder);
   }
+
+  std::string getName() const override {
+    return ::clang::ast_matchers::internal::makeMatcherNameFromType<T>();
+  }
 };
 
 /// Interface for matchers that only evaluate properties on a single
 /// node.
 template <typename T>
 class SingleNodeMatcherInterface : public MatcherInterface<T> {
 public:
   /// Returns true if the matcher matches the provided node.
public:
   /// \return \c false if this matcher will never match such a node. Otherwise,
   /// return \c true.
   bool canMatchNodesOfKind(ASTNodeKind Kind) const;
 
   /// Return a matcher that points to the same implementation, but
   ///   restricts the node types for \p Kind.
   DynTypedMatcher dynCastTo(const ASTNodeKind Kind) const;
 
-  /// Return a matcher that that points to the same implementation, but sets the
+  /// Return a matcher that points to the same implementation, but sets the
   ///   traversal kind.
   ///
   /// If the traversal kind is already set, then \c TK overrides it.
   DynTypedMatcher withTraversalKind(TraversalKind TK);
 
+  /// Return a matcher that points to the same implementation, but sets the
+  ///   name.
+  ///
+  /// If the name is already set, then \c MatcherName overrides it.
+  DynTypedMatcher withMatcherName(std::string MatcherName) const;
+
   /// Returns true if the matcher matches the given \c DynNode.
   bool matches(const DynTypedNode &DynNode, ASTMatchFinder *Finder,
                BoundNodesTreeBuilder *Builder) const;
 
   /// Same as matches(), but skips the kind check.
   ///
   /// It is faster, but the caller must ensure the node is valid for the
   /// kind of this matcher.
public:
   /// Returns the \c TraversalKind respected by calls to `match()`, if any.
   ///
   /// Most matchers will not have a traversal kind set, instead relying on the
   /// surrounding context. For those, \c llvm::None is returned.
   llvm::Optional<clang::TraversalKind> getTraversalKind() const {
     return Implementation->TraversalKind();
   }
 
+  std::string getName() const { return Implementation->getName(); }
+
 private:
   DynTypedMatcher(ASTNodeKind SupportedKind, ASTNodeKind RestrictKind,
                   IntrusiveRefCntPtr<DynMatcherInterface> Implementation)
       : SupportedKind(SupportedKind), RestrictKind(RestrictKind),
         Implementation(std::move(Implementation)) {}
 
   bool AllowBind = false;
   ASTNodeKind SupportedKind;
bool matches(const QualType &Node, ASTMatchFinder *Finder,
                                         Builder);
     }
 
     llvm::Optional<clang::TraversalKind> TraversalKind() const override {
       return this->InnerMatcher.getTraversalKind();
     }
   };
 
+  std::string getName() const { return Implementation.getName(); }
+
 private:
   // For Matcher<T> <=> Matcher<U> conversions.
   template <typename U> friend class Matcher;
 
   // For DynTypedMatcher::unconditionalConvertTo<T>.
   friend class DynTypedMatcher;
 
   static DynTypedMatcher restrictMatcher(const DynTypedMatcher &Other) {

 public:
   explicit HasOverloadedOperatorNameMatcher(std::vector<std::string> Names)
       : SingleNodeMatcherInterface<T>(), Names(std::move(Names)) {}
 
   bool matchesNode(const T &Node) const override {
     return matchesSpecialized(Node);
   }
 
+  std::string getName() const override { return "HasOverloadedOperatorName"; }
+
 private:
 
   /// CXXOperatorCallExpr exist only for calls to overloaded operators
   /// so this function returns true if the call is to an operator of the given
   /// name.
   bool matchesSpecialized(const CXXOperatorCallExpr &Node) const {
     return llvm::is_contained(Names, getOperatorSpelling(Node.getOperator()));
   }

 ///
 /// 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;
 
+  std::string getName() const override { return "HasName"; }
+
 private:
   /// Unqualified match routine.
   ///
   /// It is much faster than the full match, but it only works for unqualified
   /// matches.
   bool matchesNodeUnqualified(const NamedDecl &Node) const;
 
   /// Full match routine
public:
   explicit HasDeclarationMatcher(const Matcher<Decl> &InnerMatcher)
       : InnerMatcher(InnerMatcher) {}
 
   bool matches(const T &Node, ASTMatchFinder *Finder,
                BoundNodesTreeBuilder *Builder) const override {
     return matchesSpecialized(Node, Finder, Builder);
   }
 
+  std::string getName() const override { return "HasDeclaration"; }
+
 private:
   /// Forwards to matching on the underlying type of the QualType.
   bool matchesSpecialized(const QualType &Node, ASTMatchFinder *Finder,
                           BoundNodesTreeBuilder *Builder) const {
     if (Node.isNull())
       return false;
 
     return matchesSpecialized(*Node, Finder, Builder);
return DynTypedMatcher::trueMatcher(ASTNodeKind::getFromNodeKind<T>())
         .template unconditionalConvertTo<T>();
   }
 };
 
 /// Creates a Matcher<T> that matches if all inner matchers match.
 template <typename T>
 BindableMatcher<T>
 makeAllOfComposite(ArrayRef<const Matcher<T> *> InnerMatchers) {
-  // For the size() == 0 case, we return a "true" matcher.
+  auto MatcherName = makeMatcherNameFromType<T>();
+  // For the size() == 0 case, we wrap a "true" matcher.
   if (InnerMatchers.empty()) {
-    return BindableMatcher<T>(TrueMatcher());
+    return BindableMatcher<T>(DynTypedMatcher(Matcher<T>(TrueMatcher()))
+                                  .withMatcherName(MatcherName)
+                                  .template unconditionalConvertTo<T>());
   }
-  // For the size() == 1 case, we simply return that one matcher.
+  // For the size() == 1 case, we simply wrap that one matcher.
   // No need to wrap it in a variadic operation.
   if (InnerMatchers.size() == 1) {
-    return BindableMatcher<T>(*InnerMatchers[0]);
+    return BindableMatcher<T>(DynTypedMatcher(*InnerMatchers[0])
+                                  .withMatcherName(MatcherName)
+                                  .template unconditionalConvertTo<T>());
   }
 
   using PI = llvm::pointee_iterator<const Matcher<T> *const *>;
 
   std::vector<DynTypedMatcher> DynMatchers(PI(InnerMatchers.begin()),
                                            PI(InnerMatchers.end()));
   return BindableMatcher<T>(
       DynTypedMatcher::constructVariadic(DynTypedMatcher::VO_AllOf,
                                          ASTNodeKind::getFromNodeKind<T>(),
                                          std::move(DynMatchers))
+          .withMatcherName(MatcherName)
           .template unconditionalConvertTo<T>());
 }
 
 /// Creates a Matcher<T> that matches if
 /// T is dyn_cast'able into InnerT and all inner matchers match.
 ///
 /// Returns BindableMatcher, as matchers that use dyn_cast have
 /// the same object both to match on and to run submatchers on,
 /// so there is no ambiguity with what gets bound.
 template <typename T, typename InnerT>
 BindableMatcher<T>
 makeDynCastAllOfComposite(ArrayRef<const Matcher<InnerT> *> InnerMatchers) {
   return BindableMatcher<T>(
       makeAllOfComposite(InnerMatchers).template dynCastTo<T>());
 }
 
 /// A VariadicDynCastAllOfMatcher<SourceT, TargetT> object is a
 /// variadic functor that takes a number of Matcher<TargetT> and returns a
 /// Matcher<SourceT> that matches TargetT nodes that are matched by all of the
 /// given matchers, if SourceT can be dynamically casted into TargetT.
 ///
 /// For example:

 public:
   explicit ValueEqualsMatcher(const ValueT &ExpectedValue)
       : ExpectedValue(ExpectedValue) {}
 
   bool matchesNode(const T &Node) const override {
     return Node.getValue() == ExpectedValue;
   }
 
+  std::string getName() const override { return "ValueEquals"; }
+
 private:
   ValueT ExpectedValue;
 };
 
 /// Template specializations to easily write matchers for floating point
 /// literals.
 template <>
 inline bool ValueEqualsMatcher<FloatingLiteral, double>::matchesNode(
public:
   explicit HasAnyOperatorNameMatcher(std::vector<std::string> Names)
       : SingleNodeMatcherInterface<T>(), Names(std::move(Names)) {}
 
   bool matchesNode(const T &Node) const override {
     Optional<StringRef> OptOpName = getOpName(Node);
     return OptOpName && llvm::is_contained(Names, *OptOpName);
   }
 
+  std::string getName() const override { return "HasAnyOperatorName"; }
+
 private:
   static Optional<StringRef> getOpName(const UnaryOperator &Node) {
     return Node.getOpcodeStr(Node.getOpcode());
   }
   static Optional<StringRef> getOpName(const BinaryOperator &Node) {
     return Node.getOpcodeStr();
   }
   static StringRef getOpName(const CXXRewrittenBinaryOperator &Node) {

clang/include/clang/ASTMatchers/ASTMatchersMacros.h

#define AST_MATCHER(Type, DefineMatcher)                                       \
   class matcher_##DefineMatcher##Matcher                                       \
       : public ::clang::ast_matchers::internal::MatcherInterface<Type> {       \
   public:                                                                      \
     explicit matcher_##DefineMatcher##Matcher() = default;                     \
     bool matches(const Type &Node,                                             \
                  ::clang::ast_matchers::internal::ASTMatchFinder *Finder,      \
                  ::clang::ast_matchers::internal::BoundNodesTreeBuilder        \
                      *Builder) const override;                                 \
+    std::string getName() const override { return #DefineMatcher; }            \
   };                                                                           \
   }                                                                            \
   inline ::clang::ast_matchers::internal::Matcher<Type> DefineMatcher() {      \
     return ::clang::ast_matchers::internal::makeMatcher(                       \
         new internal::matcher_##DefineMatcher##Matcher());                     \
   }                                                                            \
   inline bool internal::matcher_##DefineMatcher##Matcher::matches(             \
       const Type &Node,                                                        \
#define AST_MATCHER_P_OVERLOAD(Type, DefineMatcher, ParamType, Param,          \
   public:                                                                      \
     explicit matcher_##DefineMatcher##OverloadId##Matcher(                     \
         ParamType const &A##Param)                                             \
         : Param(A##Param) {}                                                   \
     bool matches(const Type &Node,                                             \
                  ::clang::ast_matchers::internal::ASTMatchFinder *Finder,      \
                  ::clang::ast_matchers::internal::BoundNodesTreeBuilder        \
                      *Builder) const override;                                 \
+    std::string getName() const override { return #DefineMatcher; }            \
                                                                                \
   private:                                                                     \
     ParamType Param;                                                           \
   };                                                                           \
   }                                                                            \
   inline ::clang::ast_matchers::internal::Matcher<Type> DefineMatcher(         \
       ParamType const &Param) {                                                \
     return ::clang::ast_matchers::internal::makeMatcher(                       \
#define AST_MATCHER_P2_OVERLOAD(Type, DefineMatcher, ParamType1, Param1,       \
   public:                                                                      \
     matcher_##DefineMatcher##OverloadId##Matcher(ParamType1 const &A##Param1,  \
                                                  ParamType2 const &A##Param2)  \
         : Param1(A##Param1), Param2(A##Param2) {}                              \
     bool matches(const Type &Node,                                             \
                  ::clang::ast_matchers::internal::ASTMatchFinder *Finder,      \
                  ::clang::ast_matchers::internal::BoundNodesTreeBuilder        \
                      *Builder) const override;                                 \
+    std::string getName() const override { return #DefineMatcher; }            \
                                                                                \
   private:                                                                     \
     ParamType1 Param1;                                                         \
     ParamType2 Param2;                                                         \
   };                                                                           \
   }                                                                            \
   inline ::clang::ast_matchers::internal::Matcher<Type> DefineMatcher(         \
       ParamType1 const &Param1, ParamType2 const &Param2) {                    \
#define AST_POLYMORPHIC_MATCHER(DefineMatcher, ReturnTypesF)                   \
   template <typename NodeType>                                                 \
   class matcher_##DefineMatcher##Matcher                                       \
       : public ::clang::ast_matchers::internal::MatcherInterface<NodeType> {   \
   public:                                                                      \
     bool matches(const NodeType &Node,                                         \
                  ::clang::ast_matchers::internal::ASTMatchFinder *Finder,      \
                  ::clang::ast_matchers::internal::BoundNodesTreeBuilder        \
                      *Builder) const override;                                 \
+    std::string getName() const override { return #DefineMatcher; }            \
   };                                                                           \
   }                                                                            \
   inline ::clang::ast_matchers::internal::PolymorphicMatcher<                  \
       internal::matcher_##DefineMatcher##Matcher, ReturnTypesF>                \
   DefineMatcher() {                                                            \
     return ::clang::ast_matchers::internal::PolymorphicMatcher<                \
         internal::matcher_##DefineMatcher##Matcher, ReturnTypesF>();           \
   }                                                                            \
#define AST_POLYMORPHIC_MATCHER_P_OVERLOAD(DefineMatcher, ReturnTypesF,        \
   public:                                                                      \
     explicit matcher_##DefineMatcher##OverloadId##Matcher(                     \
         ParamType const &A##Param)                                             \
         : Param(A##Param) {}                                                   \
     bool matches(const NodeType &Node,                                         \
                  ::clang::ast_matchers::internal::ASTMatchFinder *Finder,      \
                  ::clang::ast_matchers::internal::BoundNodesTreeBuilder        \
                      *Builder) const override;                                 \
+    std::string getName() const override { return #DefineMatcher; }            \
                                                                                \
   private:                                                                     \
     ParamType Param;                                                           \
   };                                                                           \
   }                                                                            \
   inline ::clang::ast_matchers::internal::PolymorphicMatcher<                  \
       internal::matcher_##DefineMatcher##OverloadId##Matcher, ReturnTypesF,    \
       ParamType>                                                               \
#define AST_POLYMORPHIC_MATCHER_P2_OVERLOAD(DefineMatcher, ReturnTypesF,       \
   public:                                                                      \
     matcher_##DefineMatcher##OverloadId##Matcher(ParamType1 const &A##Param1,  \
                                                  ParamType2 const &A##Param2)  \
         : Param1(A##Param1), Param2(A##Param2) {}                              \
     bool matches(const NodeType &Node,                                         \
                  ::clang::ast_matchers::internal::ASTMatchFinder *Finder,      \
                  ::clang::ast_matchers::internal::BoundNodesTreeBuilder        \
                      *Builder) const override;                                 \
+    std::string getName() const override { return #DefineMatcher; }            \
                                                                                \
   private:                                                                     \
     ParamType1 Param1;                                                         \
     ParamType2 Param2;                                                         \
   };                                                                           \
   }                                                                            \
   inline ::clang::ast_matchers::internal::PolymorphicMatcher<                  \
       internal::matcher_##DefineMatcher##OverloadId##Matcher, ReturnTypesF,    \

clang/lib/ASTMatchers/ASTMatchersInternal.cpp

 
 using VariadicOperatorFunction = bool (*)(
     const DynTypedNode &DynNode, ASTMatchFinder *Finder,
     BoundNodesTreeBuilder *Builder, ArrayRef<DynTypedMatcher> InnerMatchers);
 
 template <VariadicOperatorFunction Func>
 class VariadicMatcher : public DynMatcherInterface {
 public:
-  VariadicMatcher(std::vector<DynTypedMatcher> InnerMatchers)
-      : InnerMatchers(std::move(InnerMatchers)) {}
+  VariadicMatcher(std::string MatcherName,
+                  std::vector<DynTypedMatcher> InnerMatchers)
+      : MatcherName(std::move(MatcherName)),
+        InnerMatchers(std::move(InnerMatchers)) {}
 
   bool dynMatches(const DynTypedNode &DynNode, ASTMatchFinder *Finder,
                   BoundNodesTreeBuilder *Builder) const override {
     return Func(DynNode, Finder, Builder, InnerMatchers);
   }
 
+  std::string getName() const override { return MatcherName; }
+
 private:
+  const std::string MatcherName;
   std::vector<DynTypedMatcher> InnerMatchers;
 };
 
 class IdDynMatcher : public DynMatcherInterface {
 public:
   IdDynMatcher(StringRef ID,
                IntrusiveRefCntPtr<DynMatcherInterface> InnerMatcher)
       : ID(ID), InnerMatcher(std::move(InnerMatcher)) {}
 
   bool dynMatches(const DynTypedNode &DynNode, ASTMatchFinder *Finder,
                   BoundNodesTreeBuilder *Builder) const override {
     bool Result = InnerMatcher->dynMatches(DynNode, Finder, Builder);
     if (Result) Builder->setBinding(ID, DynNode);
     return Result;
   }
 
   llvm::Optional<clang::TraversalKind> TraversalKind() const override {
     return InnerMatcher->TraversalKind();
   }
 
+  std::string getName() const override { return InnerMatcher->getName(); }
+
 private:
   const std::string ID;
   const IntrusiveRefCntPtr<DynMatcherInterface> InnerMatcher;
 };
 
+/// A matcher that specifies a particular name.
+///
+/// The name provided to the constructor overrides any name that may be
+/// specified by the `InnerMatcher`.
+class NameMatcherImpl : public DynMatcherInterface {
+public:
+  NameMatcherImpl(std::string MatcherName,
+                  IntrusiveRefCntPtr<DynMatcherInterface> InnerMatcher)
+      : MatcherName(std::move(MatcherName)),
+        InnerMatcher(std::move(InnerMatcher)) {}
+
+  bool dynMatches(const DynTypedNode &DynNode, ASTMatchFinder *Finder,
+                  BoundNodesTreeBuilder *Builder) const override {
+    return InnerMatcher->dynMatches(DynNode, Finder, Builder);
+  }
+
+  std::string getName() const override { return MatcherName; }
+
+  llvm::Optional<clang::TraversalKind> TraversalKind() const override {
+    return InnerMatcher->TraversalKind();
+  }
+
+private:
+  const std::string MatcherName;
+  const IntrusiveRefCntPtr<DynMatcherInterface> InnerMatcher;
+};
+
 /// A matcher that always returns true.
 class TrueMatcherImpl : public DynMatcherInterface {
 public:
   TrueMatcherImpl() = default;
 
   bool dynMatches(const DynTypedNode &, ASTMatchFinder *,
                   BoundNodesTreeBuilder *) const override {
     return true;
   }
+
+  std::string getName() const override { return "TrueMatcher"; }
 };
 
 /// A matcher that specifies a particular \c TraversalKind.
 ///
 /// The kind provided to the constructor overrides any kind that may be
 /// specified by the `InnerMatcher`.
 class DynTraversalMatcherImpl : public DynMatcherInterface {
 public:
   explicit DynTraversalMatcherImpl(
       clang::TraversalKind TK,
       IntrusiveRefCntPtr<DynMatcherInterface> InnerMatcher)
       : TK(TK), InnerMatcher(std::move(InnerMatcher)) {}
 
   bool dynMatches(const DynTypedNode &DynNode, ASTMatchFinder *Finder,
                   BoundNodesTreeBuilder *Builder) const override {
     return this->InnerMatcher->dynMatches(DynNode, Finder, Builder);
   }
 
   llvm::Optional<clang::TraversalKind> TraversalKind() const override {
     return TK;
   }
 
+  std::string getName() const override { return InnerMatcher->getName(); }
+
 private:
   clang::TraversalKind TK;
   IntrusiveRefCntPtr<DynMatcherInterface> InnerMatcher;
 };
 
 } // namespace
 
 bool ASTMatchFinder::isTraversalIgnoringImplicitNodes() const {
case VO_AllOf:
     // In the case of allOf() we must pass all the checks, so making
     // RestrictKind the most restrictive can save us time. This way we reject
     // invalid types earlier and we can elide the kind checks inside the
     // matcher.
     for (auto &IM : InnerMatchers) {
       RestrictKind =
           ASTNodeKind::getMostDerivedType(RestrictKind, IM.RestrictKind);
     }
-    return DynTypedMatcher(
-        SupportedKind, RestrictKind,
-        new VariadicMatcher<allOfVariadicOperator>(std::move(InnerMatchers)));
+    return DynTypedMatcher(SupportedKind, RestrictKind,
+                           new VariadicMatcher<allOfVariadicOperator>(
+                               "allOf", std::move(InnerMatchers)));
 
   case VO_AnyOf:
-    return DynTypedMatcher(
-        SupportedKind, RestrictKind,
-        new VariadicMatcher<anyOfVariadicOperator>(std::move(InnerMatchers)));
+    return DynTypedMatcher(SupportedKind, RestrictKind,
+                           new VariadicMatcher<anyOfVariadicOperator>(
+                               "anyOf", std::move(InnerMatchers)));
 
   case VO_EachOf:
-    return DynTypedMatcher(
-        SupportedKind, RestrictKind,
-        new VariadicMatcher<eachOfVariadicOperator>(std::move(InnerMatchers)));
+    return DynTypedMatcher(SupportedKind, RestrictKind,
+                           new VariadicMatcher<eachOfVariadicOperator>(
+                               "eachOf", std::move(InnerMatchers)));
 
   case VO_Optionally:
     return DynTypedMatcher(SupportedKind, RestrictKind,
                            new VariadicMatcher<optionallyVariadicOperator>(
-                               std::move(InnerMatchers)));
+                               "optionally", std::move(InnerMatchers)));
 
   case VO_UnaryNot:
     // FIXME: Implement the Not operator to take a single matcher instead of a
     // vector.
     return DynTypedMatcher(
         SupportedKind, RestrictKind,
-        new VariadicMatcher<notUnaryOperator>(std::move(InnerMatchers)));
+        new VariadicMatcher<notUnaryOperator>("not", std::move(InnerMatchers)));
   }
   llvm_unreachable("Invalid Op value.");
 }
 
 DynTypedMatcher
 DynTypedMatcher::constructRestrictedWrapper(const DynTypedMatcher &InnerMatcher,
                                             ASTNodeKind RestrictKind) {
   DynTypedMatcher Copy = InnerMatcher;
   Copy.RestrictKind = RestrictKind;
   return Copy;
 }
 
 DynTypedMatcher DynTypedMatcher::withTraversalKind(TraversalKind TK) {
   auto Copy = *this;
   Copy.Implementation =
       new DynTraversalMatcherImpl(TK, std::move(Copy.Implementation));
   return Copy;
 }
 
+DynTypedMatcher
+DynTypedMatcher::withMatcherName(std::string MatcherName) const {
+  auto Copy = *this;
+  Copy.Implementation = new NameMatcherImpl(std::move(MatcherName),
+                                            std::move(Copy.Implementation));
+  return Copy;
+}
+
 DynTypedMatcher DynTypedMatcher::trueMatcher(ASTNodeKind NodeKind) {
   // We only ever need one instance of TrueMatcherImpl, so we create a static
   // instance and reuse it to reduce the overhead of the matcher and increase
   // the chance of cache hits.
   static const llvm::IntrusiveRefCntPtr<TrueMatcherImpl> Instance =
       new TrueMatcherImpl();
   return DynTypedMatcher(NodeKind, NodeKind, Instance);
 }

clang/unittests/ASTMatchers/ASTMatchersInternalTest.cpp

 #include "llvm/Support/Host.h"
 #include "llvm/Testing/Support/SupportHelpers.h"
 #include "gtest/gtest.h"
 
 namespace clang {
 namespace ast_matchers {
 using internal::DynTypedMatcher;
 
+TEST(GetNameTest, ReturnsCorrectName) {
+  // Node
+  EXPECT_EQ(typeLoc().getName(), "`TypeLoc` Node");
+  EXPECT_EQ(typeLoc(pointerTypeLoc()).getName(), "`TypeLoc` Node");
+  EXPECT_EQ(pointerTypeLoc(hasPointeeLoc(typeLoc())).getName(),
+            "`PointerTypeLoc` Node");
+  EXPECT_EQ(varDecl(hasInitializer(expr()), hasTypeLoc(typeLoc())).getName(),
+            "`VarDecl` Node");
+  EXPECT_EQ(ompDefaultClause().getName(), "`OMPDefaultClause` Node");
+
+  // Narrowing
+  EXPECT_EQ(isConst().getName(), "isConst");
+
+  // Traversal
+  EXPECT_EQ(hasLoopVariable(varDecl()).getName(), "hasLoopVariable");
+
+  // Polymorphic
+  EXPECT_EQ(internal::Matcher<BinaryOperator>(hasLHS(expr())).getName(),
+            "hasLHS");
+
+  // Bound
+  EXPECT_EQ((typeLoc().bind("TL")).getName(), "`TypeLoc` Node");
+}
+
 #if GTEST_HAS_DEATH_TEST
 TEST(HasNameDeathTest, DiesOnEmptyName) {
   ASSERT_DEBUG_DEATH({
     DeclarationMatcher HasEmptyName = recordDecl(hasName(""));
     EXPECT_TRUE(notMatches("class X {};", HasEmptyName));
   }, "");
 }