libclang: Visit class template instantiations

[• Windfisch]

Summary

Changes clang_visitChildren()'s behaviour to also visit all explicit and implicit class template instantiations upon visiting a ClassTemplateDecl. In analogy to clang++'s -dump-ast option, they are treated as children of the ClassTemplateDecl node.

This is done by

• adding the CXCursor_ClassTemplateSpecialization cursor kind,
• adding a EnforceVisitBody flag to CursorVisitor::VisitClassTemplateSpecializationDecl, which overrides the existing early exits in that method,
• and recursively descending into theTemplateDecl->specializations().

This patch also adds a query function clang_getTemplateSpecializationKind and the associated enum type CXTemplateSpecializationKind to retrieve the specialisation kind. That way, users can distinguish between implicit instantiations (which they probably want to visit as child of the ClassTemplateDecl) and explicit instantiation (which they may want choose to ignore, because their node will reappear at the very location where the explicit instantiation takes place).

[milianw]

looks good, but this needs a test, could you add one please?

include/clang-c/Index.h

enum CXCursorKind {
 
   /**
    * \brief A code completion overload candidate.
    */
   CXCursor_OverloadCandidate             = 700
 };
 
 /**
+ * \brief Describes the kind of template specialization a cursor refers to.
+ */
+enum CXTemplateSpecializationKind {
+  
+    /// This template specialization was formed from a template-id but
+    /// has not yet been declared, defined, or instantiated.
+    CXTSK_Undeclared = 0,
+    /// This template specialization was implicitly instantiated from a
+    /// template. (C++ [temp.inst]).
+    CXTSK_ImplicitInstantiation,
+    /// This template specialization was declared or defined by an
+    /// explicit specialization (C++ [temp.expl.spec]) or partial
+    /// specialization (C++ [temp.class.spec]).
+    CXTSK_ExplicitSpecialization,
+    /// This template specialization was instantiated from a template
+    /// due to an explicit instantiation declaration request
+    /// (C++11 [temp.explicit]).
+    CXTSK_ExplicitInstantiationDeclaration,
+    /// This template specialization was instantiated from a template
+    /// due to an explicit instantiation definition request
+    /// (C++ [temp.explicit]).
+    CXTSK_ExplicitInstantiationDefinition
+};
+
+/**
  * \brief A cursor representing some element in the abstract syntax tree for
  * a translation unit.
  *
  * The cursor abstraction unifies the different kinds of entities in a
  * program--declaration, statements, expressions, references to declarations,
  * etc.--under a single "cursor" abstraction with a common set of operations.
  * Common operation for a cursor include: getting the physical location in
  * a source file where the cursor points, getting the name associated with a

  * \param C The cursor to query. This cursor should represent a template
  * declaration.
  *
  * \returns The cursor kind of the specializations that would be generated
  * by instantiating the template \p C. If \p C is not a template, returns
  * \c CXCursor_NoDeclFound.
  */
 CINDEX_LINKAGE enum CXCursorKind clang_getTemplateCursorKind(CXCursor C);
-  
 /**
+ * \brief Given a cursor that represents a template, determine the kind
+ * of specialization (e.g. implicit or explicit instantiation)
+ *
+ * This routine can be used to eliminate duplicate explicit template
+ * instantiations that occur both as a child of the template, and at
+ * the place where they got explicitly instantiated. By ignoring explicit
+ * instantiations which parent is / isn't the template itself, no
+ * duplicates will occur.
+ *
+ * \param C The cursor to query. This cursor should represent a template
+ * declaration.
+ *
+ * \returns The template specialization kind. If \p C is not a template, returns
+ * \c CXTSK_Undeclared.
+ */
+CINDEX_LINKAGE enum CXTemplateSpecializationKind clang_getTemplateSpecializationKind(CXCursor C);
+  
+/**
  * \brief Given a cursor that may represent a specialization or instantiation
  * of a template, retrieve the cursor that represents the template that it
  * specializes or from which it was instantiated.
  *
  * This routine determines the template involved both for explicit 
  * specializations of templates and for implicit instantiations of the template,
  * both of which are referred to as "specializations". For a class template
  * specialization (e.g., \c std::vector<bool>), this routine will return 

lib/Sema/SemaCodeComplete.cpp

switch (D->getKind()) {
     case Decl::TemplateTypeParm:   return CXCursor_TemplateTypeParameter;
     case Decl::NonTypeTemplateParm:return CXCursor_NonTypeTemplateParameter;
     case Decl::TemplateTemplateParm:return CXCursor_TemplateTemplateParameter;
     case Decl::FunctionTemplate:   return CXCursor_FunctionTemplate;
     case Decl::ClassTemplate:      return CXCursor_ClassTemplate;
     case Decl::AccessSpec:         return CXCursor_CXXAccessSpecifier;
     case Decl::ClassTemplatePartialSpecialization:
       return CXCursor_ClassTemplatePartialSpecialization;
+    case Decl::ClassTemplateSpecialization:
+      return CXCursor_ClassTemplateSpecialization;
     case Decl::UsingDirective:     return CXCursor_UsingDirective;
     case Decl::StaticAssert:       return CXCursor_StaticAssert;
     case Decl::Friend:             return CXCursor_FriendDecl;
     case Decl::TranslationUnit:    return CXCursor_TranslationUnit;
       
     case Decl::Using:
     case Decl::UnresolvedUsingValue:
     case Decl::UnresolvedUsingTypename: 

tools/libclang/CIndex.cpp

bool CursorVisitor::VisitChildren(CXCursor Cursor) {
   // done.
   SetParentRAII SetParent(Parent, StmtParent, Cursor);
 
   if (clang_isDeclaration(Cursor.kind)) {
     Decl *D = const_cast<Decl *>(getCursorDecl(Cursor));
     if (!D)
       return false;
 
-    return VisitAttributes(D) || Visit(D);
+    if (VisitAttributes(D))
+      return true;
+
+    if (Cursor.kind == CXCursor_ClassTemplateSpecialization)
+      return VisitClassTemplateSpecializationDecl(static_cast<ClassTemplateSpecializationDecl*>(D), /*EnforceVisitBody*/ true);
+    else
+      return Visit(D);
   }
 
   if (clang_isStatement(Cursor.kind)) {
     if (const Stmt *S = getCursorStmt(Cursor))
       return Visit(S);
 
     return false;
   }
bool CursorVisitor::VisitTypedefDecl(TypedefDecl *D) {
   return false;
 }
 
 bool CursorVisitor::VisitTagDecl(TagDecl *D) {
   return VisitDeclContext(D);
 }
 
 bool CursorVisitor::VisitClassTemplateSpecializationDecl(
-                                          ClassTemplateSpecializationDecl *D) {
-  bool ShouldVisitBody = false;
+                                          ClassTemplateSpecializationDecl *D, bool EnforceVisitBody) {
+  bool ShouldVisitBody = EnforceVisitBody;
+  if (!EnforceVisitBody)
     switch (D->getSpecializationKind()) {
     case TSK_Undeclared:
     case TSK_ImplicitInstantiation:
       // Nothing to visit
       return false;
         
     case TSK_ExplicitInstantiationDeclaration:
     case TSK_ExplicitInstantiationDefinition:
       break;
         
     case TSK_ExplicitSpecialization:
       ShouldVisitBody = true;
       break;
     }
   
   // Visit the template arguments used in the specialization.
   if (TypeSourceInfo *SpecType = D->getTypeAsWritten()) {
     TypeLoc TL = SpecType->getTypeLoc();
     if (TemplateSpecializationTypeLoc TSTLoc =
             TL.getAs<TemplateSpecializationTypeLoc>()) {
       for (unsigned I = 0, N = TSTLoc.getNumArgs(); I != N; ++I)
         if (VisitTemplateArgumentLoc(TSTLoc.getArgLoc(I)))

 
 bool CursorVisitor::VisitClassTemplateDecl(ClassTemplateDecl *D) {
   // FIXME: Visit the "outer" template parameter lists on the TagDecl
   // before visiting these template parameters.
   if (VisitTemplateParameters(D->getTemplateParameters()))
     return true;
   
   auto* CD = D->getTemplatedDecl();
-  return VisitAttributes(CD) || VisitCXXRecordDecl(CD);
+  if (VisitAttributes(CD))
+    return true;
+  if (VisitCXXRecordDecl(CD))
+    return true;
+
+  for (auto *Child : D->specializations())
+    if (Visit(MakeCXCursor(Child, TU)))
+      return true; // FIXME do this for function and var templates too.
+      // inspired by tools/clang/lib/AST/ASTDumper.cpp, ASTDumper::VisitTemplateDecl
+      // which is called from VisitClassTemplateDecl etc.
+  
+  return false;
 }
 
 bool CursorVisitor::VisitTemplateTemplateParmDecl(TemplateTemplateParmDecl *D) {
   if (VisitTemplateParameters(D->getTemplateParameters()))
     return true;
   
   if (D->hasDefaultArgument() && !D->defaultArgumentWasInherited() &&
       VisitTemplateArgumentLoc(D->getDefaultArgument()))

tools/libclang/CIndexCXX.cpp

enum CXCursorKind clang_getTemplateCursorKind(CXCursor C) {
       
   default:
     break;
   }
   
   return CXCursor_NoDeclFound;
 }
 
+enum CXTemplateSpecializationKind clang_getTemplateSpecializationKind(CXCursor C) {
+  using namespace clang::cxcursor;
+  
+  if (C.kind == CXCursor_ClassTemplateSpecialization)
+  {
+    switch (static_cast<const ClassTemplateSpecializationDecl *>(getCursorDecl(C))->getSpecializationKind())
+    {
+      #define TRANSL(val) case val: return CX##val;
+      TRANSL(TSK_Undeclared)
+      TRANSL(TSK_ImplicitInstantiation)
+      TRANSL(TSK_ExplicitSpecialization)
+      TRANSL(TSK_ExplicitInstantiationDeclaration)
+      TRANSL(TSK_ExplicitInstantiationDefinition)
+      #undef TRANSL
+    }
+  }
+  return CXTSK_Undeclared;
+}
+
 CXCursor clang_getSpecializedCursorTemplate(CXCursor C) {
   if (!clang_isDeclaration(C.kind))
     return clang_getNullCursor();
     
   const Decl *D = getCursorDecl(C);
   if (!D)
     return clang_getNullCursor();
 

tools/libclang/CursorVisitor.h

public:
   bool VisitAttributes(Decl *D);
   bool VisitBlockDecl(BlockDecl *B);
   bool VisitCXXRecordDecl(CXXRecordDecl *D);
   Optional<bool> shouldVisitCursor(CXCursor C);
   bool VisitDeclContext(DeclContext *DC);
   bool VisitTranslationUnitDecl(TranslationUnitDecl *D);
   bool VisitTypedefDecl(TypedefDecl *D);
   bool VisitTagDecl(TagDecl *D);
-  bool VisitClassTemplateSpecializationDecl(ClassTemplateSpecializationDecl *D);
+  bool VisitClassTemplateSpecializationDecl(ClassTemplateSpecializationDecl *D, bool EnforceVisitBody = false);
   bool VisitClassTemplatePartialSpecializationDecl(
                                      ClassTemplatePartialSpecializationDecl *D);
   bool VisitTemplateTypeParmDecl(TemplateTypeParmDecl *D);
   bool VisitEnumConstantDecl(EnumConstantDecl *D);
   bool VisitDeclaratorDecl(DeclaratorDecl *DD);
   bool VisitFunctionDecl(FunctionDecl *ND);
   bool VisitFieldDecl(FieldDecl *D);
   bool VisitVarDecl(VarDecl *);

tools/libclang/libclang.exports

 clang_getRemappings
 clang_getRemappingsFromFileList
 clang_getResultType
 clang_getSkippedRanges
 clang_getSpecializedCursorTemplate
 clang_getSpellingLocation
 clang_getTUResourceUsageName
 clang_getTemplateCursorKind
+clang_getTemplateSpecializationKind
 clang_getTokenExtent
 clang_getTokenKind
 clang_getTokenLocation
 clang_getTokenSpelling
 clang_getTranslationUnitCursor
 clang_getTranslationUnitSpelling
 clang_getTranslationUnitTargetInfo
 clang_getTypeDeclaration