clang/Testing/TestAST.h

0001 //===--- TestAST.h - Build clang ASTs for testing -------------------------===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 // In normal operation of Clang, the FrontendAction's lifecycle both creates
0010 // and destroys the AST, and code should operate on it during callbacks in
0011 // between (e.g. via ASTConsumer).
0012 //
0013 // For tests it is often more convenient to parse an AST from code, and keep it
0014 // alive as a normal local object, with assertions as straight-line code.
0015 // TestAST provides such an interface.
0016 // (ASTUnit can be used for this purpose, but is a production library with
0017 // broad scope and complicated API).
0018 //
0019 //===----------------------------------------------------------------------===//
0020
0021 #ifndef LLVM_CLANG_TESTING_TESTAST_H
0022 #define LLVM_CLANG_TESTING_TESTAST_H
0023
0024 #include "clang/Basic/LLVM.h"
0025 #include "clang/Frontend/CompilerInstance.h"
0026 #include "clang/Testing/CommandLineArgs.h"
0027 #include "llvm/ADT/StringRef.h"
0028 #include <string>
0029 #include <vector>
0030
0031 namespace clang {
0032
0033 /// Specifies a virtual source file to be parsed as part of a test.
0034 struct TestInputs {
0035   TestInputs() = default;
0036   TestInputs(StringRef Code) : Code(Code) {}
0037
0038   /// The source code of the input file to be parsed.
0039   std::string Code;
0040
0041   /// The language to parse as.
0042   /// This affects the -x and -std flags used, and the filename.
0043   TestLanguage Language = TestLanguage::Lang_OBJCXX;
0044
0045   /// Extra argv to pass to clang -cc1.
0046   std::vector<std::string> ExtraArgs = {};
0047
0048   /// Extra virtual files that are available to be #included.
0049   /// Keys are plain filenames ("foo.h"), values are file content.
0050   llvm::StringMap<std::string> ExtraFiles = {};
0051
0052   /// Root of execution, all relative paths in Args/Files are resolved against
0053   /// this.
0054   std::string WorkingDir;
0055
0056   /// Filename to use for translation unit. A default will be used when empty.
0057   std::string FileName;
0058
0059   /// By default, error diagnostics during parsing are reported as gtest errors.
0060   /// To suppress this, set ErrorOK or include "error-ok" in a comment in Code.
0061   /// In either case, all diagnostics appear in TestAST::diagnostics().
0062   bool ErrorOK = false;
0063
0064   /// The action used to parse the code.
0065   /// By default, a SyntaxOnlyAction is used.
0066   std::function<std::unique_ptr<FrontendAction>()> MakeAction;
0067 };
0068
0069 /// The result of parsing a file specified by TestInputs.
0070 ///
0071 /// The ASTContext, Sema etc are valid as long as this object is alive.
0072 class TestAST {
0073 public:
0074   /// Constructing a TestAST parses the virtual file.
0075   ///
0076   /// To keep tests terse, critical errors (e.g. invalid flags) are reported as
0077   /// unit test failures with ADD_FAILURE() and produce an empty ASTContext,
0078   /// Sema etc. This frees the test code from handling these explicitly.
0079   TestAST(const TestInputs &);
0080   TestAST(StringRef Code) : TestAST(TestInputs(Code)) {}
0081   TestAST(TestAST &&M);
0082   TestAST &operator=(TestAST &&);
0083   ~TestAST();
0084
0085   /// Provides access to the AST context and other parts of Clang.
0086
0087   ASTContext &context() { return Clang->getASTContext(); }
0088   Sema &sema() { return Clang->getSema(); }
0089   SourceManager &sourceManager() { return Clang->getSourceManager(); }
0090   FileManager &fileManager() { return Clang->getFileManager(); }
0091   Preprocessor &preprocessor() { return Clang->getPreprocessor(); }
0092   FrontendAction &action() { return *Action; }
0093
0094   /// Returns diagnostics emitted during parsing.
0095   /// (By default, errors cause test failures, see TestInputs::ErrorOK).
0096   llvm::ArrayRef<StoredDiagnostic> diagnostics() { return Diagnostics; }
0097
0098 private:
0099   void clear();
0100   std::unique_ptr<FrontendAction> Action;
0101   std::unique_ptr<CompilerInstance> Clang;
0102   std::vector<StoredDiagnostic> Diagnostics;
0103 };
0104
0105 } // end namespace clang
0106
0107 #endif