1 //===--- TestAST.h - Build clang ASTs for testing -------------------------===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 // In normal operation of Clang, the FrontendAction's lifecycle both creates
10 // and destroys the AST, and code should operate on it during callbacks in
11 // between (e.g. via ASTConsumer).
12 //
13 // For tests it is often more convenient to parse an AST from code, and keep it
14 // alive as a normal local object, with assertions as straight-line code.
15 // TestAST provides such an interface.
16 // (ASTUnit can be used for this purpose, but is a production library with
17 // broad scope and complicated API).
18 //
19 //===----------------------------------------------------------------------===//
20 
21 #ifndef LLVM_CLANG_TESTING_TESTAST_H
22 #define LLVM_CLANG_TESTING_TESTAST_H
23 
24 #include "clang/Basic/LLVM.h"
25 #include "clang/Frontend/CompilerInstance.h"
26 #include "clang/Testing/CommandLineArgs.h"
27 #include "llvm/ADT/StringRef.h"
28 #include <string>
29 #include <vector>
30 
31 namespace clang {
32 
33 /// Specifies a virtual source file to be parsed as part of a test.
34 struct TestInputs {
35   TestInputs() = default;
TestInputsTestInputs36   TestInputs(StringRef Code) : Code(Code) {}
37 
38   /// The source code of the input file to be parsed.
39   std::string Code;
40 
41   /// The language to parse as.
42   /// This affects the -x and -std flags used, and the filename.
43   TestLanguage Language = TestLanguage::Lang_OBJCXX;
44 
45   /// Extra argv to pass to clang -cc1.
46   std::vector<std::string> ExtraArgs = {};
47 
48   /// Extra virtual files that are available to be #included.
49   /// Keys are plain filenames ("foo.h"), values are file content.
50   llvm::StringMap<std::string> ExtraFiles = {};
51 
52   /// Filename to use for translation unit. A default will be used when empty.
53   std::string FileName;
54 
55   /// By default, error diagnostics during parsing are reported as gtest errors.
56   /// To suppress this, set ErrorOK or include "error-ok" in a comment in Code.
57   /// In either case, all diagnostics appear in TestAST::diagnostics().
58   bool ErrorOK = false;
59 
60   /// The action used to parse the code.
61   /// By default, a SyntaxOnlyAction is used.
62   std::function<std::unique_ptr<FrontendAction>()> MakeAction;
63 };
64 
65 /// The result of parsing a file specified by TestInputs.
66 ///
67 /// The ASTContext, Sema etc are valid as long as this object is alive.
68 class TestAST {
69 public:
70   /// Constructing a TestAST parses the virtual file.
71   ///
72   /// To keep tests terse, critical errors (e.g. invalid flags) are reported as
73   /// unit test failures with ADD_FAILURE() and produce an empty ASTContext,
74   /// Sema etc. This frees the test code from handling these explicitly.
75   TestAST(const TestInputs &);
TestAST(StringRef Code)76   TestAST(StringRef Code) : TestAST(TestInputs(Code)) {}
77   TestAST(TestAST &&M);
78   TestAST &operator=(TestAST &&);
79   ~TestAST();
80 
81   /// Provides access to the AST context and other parts of Clang.
82 
context()83   ASTContext &context() { return Clang->getASTContext(); }
sema()84   Sema &sema() { return Clang->getSema(); }
sourceManager()85   SourceManager &sourceManager() { return Clang->getSourceManager(); }
fileManager()86   FileManager &fileManager() { return Clang->getFileManager(); }
preprocessor()87   Preprocessor &preprocessor() { return Clang->getPreprocessor(); }
action()88   FrontendAction &action() { return *Action; }
89 
90   /// Returns diagnostics emitted during parsing.
91   /// (By default, errors cause test failures, see TestInputs::ErrorOK).
diagnostics()92   llvm::ArrayRef<StoredDiagnostic> diagnostics() { return Diagnostics; }
93 
94 private:
95   void clear();
96   std::unique_ptr<FrontendAction> Action;
97   std::unique_ptr<CompilerInstance> Clang;
98   std::vector<StoredDiagnostic> Diagnostics;
99 };
100 
101 } // end namespace clang
102 
103 #endif
104