Allow the creation of human-friendly ASTDumper to arbitrary output stream

[whisperity]

Summary

ASTPrinter allows setting the ouput to any O-Stream, but that printer creates source-code-like syntax (and is also marked with a FIXME). The nice, colourful, mostly human-readable ASTDumper only works on the standard output, which is not feasible in case a user wants to see the AST of a file through a code navigation/comprehension tool.

This small addition of an overload solves generating a nice colourful AST block for the users of a tool I'm working on, CodeCompass, as opposed to having to duplicate the behaviour of definitions that only exist in the anonymous namespace of implementation TUs related to this module.

[alexfh]

Looks good to me. One optional comment.

include/clang/Frontend/ASTConsumers.h

39–41 ↗

(On Diff #140437)

With just three users of the old API it might make sense to just add a parameter to it and update the callers instead of adding another override.

[whisperity]

• Overload removed, now only one CreateASTDumper function remains.
• Updated the call sites of this function to use this call.

[whisperity]

@alexfh I have updated the patch. I don't have commit rights, so if you think this is good to go, could you please commit for me?

[alexfh]

Another couple of nits.

docs/HowToSetupToolingForLLVM.rst

136 ↗

(On Diff #141194)

Please add an argument comment for nullptr, e.g.

return clang::CreateASTDumper(/*OS=*/nullptr, ...);

or maybe

return clang::CreateASTDumper(nullptr /*dump to stderr*/, ...);

Same in the actual callers below.

include/clang/Frontend/ASTConsumers.h

38 ↗

(On Diff #141194)

Add "When OS is nullptr, dumps AST to stderr."

[whisperity]

Added comments on what nullptr means at call sites.

[whisperity]

It is also std-out (llvm::outs()) in case of nullptr and not std-err.

[alexfh]

LG. I'll commit the patch for you.

cfe/trunk/docs/HowToSetupToolingForLLVM.rst

.. code-block:: console
   ...
   $ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-print -ast-dump-filter ActionFactory::newASTConsumer
   Processing: tools/clang/tools/clang-check/ClangCheck.cpp.
   Printing <anonymous namespace>::ActionFactory::newASTConsumer:
   clang::ASTConsumer *newASTConsumer() {
       if (this->ASTList.operator _Bool())
           return clang::CreateASTDeclNodeLister();
       if (this->ASTDump.operator _Bool())
-          return clang::CreateASTDumper(this->ASTDumpFilter);
+          return clang::CreateASTDumper(nullptr /*Dump to stdout.*/,
+                                        this->ASTDumpFilter);
       if (this->ASTPrint.operator _Bool())
           return clang::CreateASTPrinter(&llvm::outs(), this->ASTDumpFilter);
       return new clang::ASTConsumer();
   }
 
 (Experimental) Using Ninja Build System
 =======================================
 

cfe/trunk/include/clang/Frontend/ASTConsumers.h

 
 // AST pretty-printer: prints out the AST in a format that is close to the
 // original C code.  The output is intended to be in a format such that
 // clang could re-parse the output back into the same AST, but the
 // implementation is still incomplete.
 std::unique_ptr<ASTConsumer> CreateASTPrinter(std::unique_ptr<raw_ostream> OS,
                                               StringRef FilterString);
 
-// AST dumper: dumps the raw AST in human-readable form to stderr; this is
-// intended for debugging.
-std::unique_ptr<ASTConsumer> CreateASTDumper(StringRef FilterString,
+// AST dumper: dumps the raw AST in human-readable form to the given output
+// stream, or stdout if OS is nullptr.
+std::unique_ptr<ASTConsumer> CreateASTDumper(std::unique_ptr<raw_ostream> OS,
+                                             StringRef FilterString,
                                              bool DumpDecls, bool Deserialize,
                                              bool DumpLookups);
 
 // AST Decl node lister: prints qualified names of all filterable AST Decl
 // nodes.
 std::unique_ptr<ASTConsumer> CreateASTDeclNodeLister();
 
 // Graphical AST viewer: for each function definition, creates a graph of

cfe/trunk/lib/Frontend/ASTConsumers.cpp

 
 std::unique_ptr<ASTConsumer>
 clang::CreateASTPrinter(std::unique_ptr<raw_ostream> Out,
                         StringRef FilterString) {
   return llvm::make_unique<ASTPrinter>(std::move(Out), ASTPrinter::Print,
                                        FilterString);
 }
 
-std::unique_ptr<ASTConsumer> clang::CreateASTDumper(StringRef FilterString,
-                                                    bool DumpDecls,
-                                                    bool Deserialize,
-                                                    bool DumpLookups) {
+std::unique_ptr<ASTConsumer>
+clang::CreateASTDumper(std::unique_ptr<raw_ostream> Out,
+                       StringRef FilterString,
   assert((DumpDecls || Deserialize || DumpLookups) && "nothing to dump");
-  return llvm::make_unique<ASTPrinter>(nullptr,
+  return llvm::make_unique<ASTPrinter>(std::move(Out),
                                        Deserialize ? ASTPrinter::DumpFull :
                                        DumpDecls ? ASTPrinter::Dump :
                                        ASTPrinter::None,
                                        FilterString, DumpLookups);
 }
 
 std::unique_ptr<ASTConsumer> clang::CreateASTDeclNodeLister() {
   return llvm::make_unique<ASTDeclNodeLister>(nullptr);

cfe/trunk/lib/Frontend/FrontendActions.cpp

ASTPrintAction::CreateASTConsumer(CompilerInstance &CI, StringRef InFile) {
   if (std::unique_ptr<raw_ostream> OS =
           CI.createDefaultOutputFile(false, InFile))
     return CreateASTPrinter(std::move(OS), CI.getFrontendOpts().ASTDumpFilter);
   return nullptr;
 }
 
 std::unique_ptr<ASTConsumer>
 ASTDumpAction::CreateASTConsumer(CompilerInstance &CI, StringRef InFile) {
-  return CreateASTDumper(CI.getFrontendOpts().ASTDumpFilter,
+  return CreateASTDumper(nullptr /*Dump to stdout.*/,
+                         CI.getFrontendOpts().ASTDumpFilter,
                          CI.getFrontendOpts().ASTDumpDecls,
                          CI.getFrontendOpts().ASTDumpAll,
                          CI.getFrontendOpts().ASTDumpLookups);
 }
 
 std::unique_ptr<ASTConsumer>
 ASTDeclListAction::CreateASTConsumer(CompilerInstance &CI, StringRef InFile) {
   return CreateASTDeclNodeLister();

cfe/trunk/tools/clang-check/ClangCheck.cpp

 };
 
 class ClangCheckActionFactory {
 public:
   std::unique_ptr<clang::ASTConsumer> newASTConsumer() {
     if (ASTList)
       return clang::CreateASTDeclNodeLister();
     if (ASTDump)
-      return clang::CreateASTDumper(ASTDumpFilter, /*DumpDecls=*/true,
+      return clang::CreateASTDumper(nullptr /*Dump to stdout.*/,
+                                    ASTDumpFilter,
+                                    /*DumpDecls=*/true,
                                     /*Deserialize=*/false,
                                     /*DumpLookups=*/false);
     if (ASTPrint)
       return clang::CreateASTPrinter(nullptr, ASTDumpFilter);
     return llvm::make_unique<clang::ASTConsumer>();
   }
 };
 

cfe/trunk/tools/clang-import-test/clang-import-test.cpp

llvm::Expected<CIAndOrigins> Parse(const std::string &Path,
   std::vector<std::unique_ptr<ASTConsumer>> ASTConsumers;
 
   auto LLVMCtx = llvm::make_unique<llvm::LLVMContext>();
   ASTConsumers.push_back(
       init_convenience::BuildCodeGen(CI.getCompilerInstance(), *LLVMCtx));
   auto &CG = *static_cast<CodeGenerator *>(ASTConsumers.back().get());
 
   if (ShouldDumpAST)
-    ASTConsumers.push_back(CreateASTDumper("", true, false, false));
+    ASTConsumers.push_back(CreateASTDumper(nullptr /*Dump to stdout.*/,
+                                           "", true, false, false));
 
   CI.getDiagnosticClient().BeginSourceFile(
       CI.getCompilerInstance().getLangOpts(),
       &CI.getCompilerInstance().getPreprocessor());
   MultiplexConsumer Consumers(std::move(ASTConsumers));
   Consumers.Initialize(CI.getASTContext());
 
   if (llvm::Error PE = ParseSource(Path, CI.getCompilerInstance(), Consumers))