+ +

How to write RecursiveASTVisitor based ASTFrontendActions.

+ + +

Introduction

+ + +In this tutorial you will learn how to create a FrontendAction that uses +a RecursiveASTVisitor to find CXXRecordDecl AST nodes with a specified name. + + +

Creating a FrontendAction

+ + +

When writing a clang based tool like a Clang Plugin or a standalone tool +based on LibTooling, the common entry point is the FrontendAction. +FrontendAction is an interface that allows execution of user specific actions +as part of the compilation. To run tools over the AST clang provides the +convenience interface ASTFrontendAction, which takes care of executing the +action. The only part left is to implement the CreateASTConsumer method that +returns an ASTConsumer per translation unit.

+  class FindNamedClassAction : public clang::ASTFrontendAction {
+  public:
+    virtual clang::ASTConsumer *CreateASTConsumer(
+      clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+      return new FindNamedClassConsumer;
+    }
+  };
+

+ + +

Creating an ASTConsumer

+ + +

ASTConsumer is an interface used to write generic actions on an AST, +regardless of how the AST was produced. ASTConsumer provides many different +entry points, but for our use case the only one needed is HandleTranslationUnit, +which is called with the ASTContext for the translation unit.

+  class FindNamedClassConsumer : public clang::ASTConsumer {
+  public:
+    virtual void HandleTranslationUnit(clang::ASTContext &Context) {
+      // Traversing the translation unit decl via a RecursiveASTVisitor
+      // will visit all nodes in the AST.
+      Visitor.TraverseDecl(Context.getTranslationUnitDecl());
+    }
+  private:
+    // A RecursiveASTVisitor implementation.
+    FindNamedClassVisitor Visitor;
+  };
+

+ + +

Using the RecursiveASTVisitor

+ + +

Now that everything is hooked up, the next step is to implement a +RecursiveASTVisitor to extract the relevant information from the AST.

The RecursiveASTVisitor provides hooks of the form +bool VisitNodeType(NodeType *) for most AST nodes; the exception are TypeLoc +nodes, which are passed by-value. We only need to implement the methods for the +relevant node types. +

Let's start by writing a RecursiveASTVisitor that visits all CXXRecordDecl's. +

+  class FindNamedClassVisitor
+    : public RecursiveASTVisitor<FindNamedClassVisitor> {
+  public:
+    bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+      // For debugging, dumping the AST nodes will show which nodes are already
+      // being visited.
+      Declaration->dump();
+
+      // The return value indicates whether we want the visitation to proceed.
+      // Return false to stop the traversal of the AST.
+      return true;
+    }
+  };
+

In the methods of our RecursiveASTVisitor we can now use the full power of +the Clang AST to drill through to the parts that are interesting for us. For +example, to find all class declaration with a certain name, we can check for a +specific qualified name: +

+  bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+    if (Declaration->getQualifiedNameAsString() == "n::m::C")
+      Declaration->dump();
+    return true;
+  }
+

+ + +

Accessing the SourceManager and ASTContext

+ + +

Some of the information about the AST, like source locations and global +identifier information, are not stored in the AST nodes themselves, but in +the ASTContext and its associated source manager. To retrieve them we need to +hand the ASTContext into our RecursiveASTVisitor implementation.

The ASTContext is available from the CompilerInstance during the call +to CreateASTConsumer. We can thus extract it there and hand it into our +freshly created FindNamedClassConsumer:

+  virtual clang::ASTConsumer *CreateASTConsumer(
+    clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+    return new FindNamedClassConsumer(&Compiler.getASTContext());
+  }
+

+ +

Now that the ASTContext is available in the RecursiveASTVisitor, we can do +more interesting things with AST nodes, like looking up their source +locations:

+  bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+    if (Declaration->getQualifiedNameAsString() == "n::m::C") {
+      // getFullLoc uses the ASTContext's SourceManager to resolve the source
+      // location and break it up into its line and column parts.
+      FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+      if (FullLocation.isValid())
+        llvm::outs() << "Found declaration at "
+                     << FullLocation.getSpellingLineNumber() << ":"
+                     << FullLocation.getSpellingColumnNumber() << "\n";
+    }
+    return true;
+  }
+

+ + +

Putting it all together

+ + +

Now we can combine all of the above into a small example program:

+  #include "clang/AST/ASTConsumer.h"
+  #include "clang/AST/RecursiveASTVisitor.h"
+  #include "clang/Frontend/CompilerInstance.h"
+  #include "clang/Frontend/FrontendAction.h"
+  #include "clang/Tooling/Tooling.h"
+
+  using namespace clang;
+
+  class FindNamedClassVisitor
+    : public RecursiveASTVisitor<FindNamedClassVisitor> {
+  public:
+    explicit FindNamedClassVisitor(ASTContext *Context)
+      : Context(Context) {}
+
+    bool VisitCXXRecordDecl(CXXRecordDecl *Declaration) {
+      if (Declaration->getQualifiedNameAsString() == "n::m::C") {
+        FullSourceLoc FullLocation = Context->getFullLoc(Declaration->getLocStart());
+        if (FullLocation.isValid())
+          llvm::outs() << "Found declaration at "
+                       << FullLocation.getSpellingLineNumber() << ":"
+                       << FullLocation.getSpellingColumnNumber() << "\n";
+      }
+      return true;
+    }
+
+  private:
+    ASTContext *Context;
+  };
+
+  class FindNamedClassConsumer : public clang::ASTConsumer {
+  public:
+    explicit FindNamedClassConsumer(ASTContext *Context)
+      : Visitor(Context) {}
+
+    virtual void HandleTranslationUnit(clang::ASTContext &Context) {
+      Visitor.TraverseDecl(Context.getTranslationUnitDecl());
+    }
+  private:
+    FindNamedClassVisitor Visitor;
+  };
+
+  class FindNamedClassAction : public clang::ASTFrontendAction {
+  public:
+    virtual clang::ASTConsumer *CreateASTConsumer(
+      clang::CompilerInstance &Compiler, llvm::StringRef InFile) {
+      return new FindNamedClassConsumer(&Compiler.getASTContext());
+    }
+  };
+
+  int main(int argc, char **argv) {
+    if (argc > 1) {
+      clang::tooling::runToolOnCode(new FindNamedClassAction, argv[1]);
+    }
+  }
+

+ +

We store this into a file called FindClassDecls.cpp and create the following +CMakeLists.txt to link it:

+set(LLVM_USED_LIBS clangTooling)
+
+add_clang_executable(find-class-decls FindClassDecls.cpp)
+

+ +

When running this tool over a small code snippet it will output all +declarations of a class n::m::C it found:

+  $ ./bin/find-class-decls "namespace n { namespace m { class C {}; } }"
+  Found declaration at 1:29
+

+ +