1 //===--- ParsedAST.h - Building translation units ----------------*- C++-*-===//
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 // This file exposes building a file as if it were open in clangd, and defines
10 // the ParsedAST structure that holds the results.
11 //
12 // This is similar to a clang -fsyntax-only run that produces a clang AST, but
13 // we have several customizations:
14 //  - preamble handling
15 //  - capturing diagnostics for later access
16 //  - running clang-tidy checks checks
17 //
18 //===----------------------------------------------------------------------===//
19 
20 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_PARSEDAST_H
21 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_PARSEDAST_H
22 
23 #include "CollectMacros.h"
24 #include "Compiler.h"
25 #include "Diagnostics.h"
26 #include "Headers.h"
27 #include "Preamble.h"
28 #include "index/CanonicalIncludes.h"
29 #include "support/Path.h"
30 #include "clang/Frontend/FrontendAction.h"
31 #include "clang/Frontend/PrecompiledPreamble.h"
32 #include "clang/Lex/Preprocessor.h"
33 #include "clang/Tooling/CompilationDatabase.h"
34 #include "clang/Tooling/Syntax/Tokens.h"
35 #include "llvm/ADT/ArrayRef.h"
36 #include "llvm/ADT/None.h"
37 #include "llvm/ADT/Optional.h"
38 #include "llvm/ADT/StringRef.h"
39 #include <memory>
40 #include <string>
41 #include <vector>
42 
43 namespace clang {
44 namespace clangd {
45 class SymbolIndex;
46 
47 /// Stores and provides access to parsed AST.
48 class ParsedAST {
49 public:
50   /// Attempts to run Clang and store the parsed AST.
51   /// If \p Preamble is non-null it is reused during parsing.
52   /// This function does not check if preamble is valid to reuse.
53   static llvm::Optional<ParsedAST>
54   build(llvm::StringRef Filename, const ParseInputs &Inputs,
55         std::unique_ptr<clang::CompilerInvocation> CI,
56         llvm::ArrayRef<Diag> CompilerInvocationDiags,
57         std::shared_ptr<const PreambleData> Preamble);
58 
59   ParsedAST(ParsedAST &&Other);
60   ParsedAST &operator=(ParsedAST &&Other);
61 
62   ~ParsedAST();
63 
64   /// Note that the returned ast will not contain decls from the preamble that
65   /// were not deserialized during parsing. Clients should expect only decls
66   /// from the main file to be in the AST.
67   ASTContext &getASTContext();
68   const ASTContext &getASTContext() const;
69 
70   Preprocessor &getPreprocessor();
71   std::shared_ptr<Preprocessor> getPreprocessorPtr();
72   const Preprocessor &getPreprocessor() const;
73 
getSourceManager()74   SourceManager &getSourceManager() {
75     return getASTContext().getSourceManager();
76   }
getSourceManager()77   const SourceManager &getSourceManager() const {
78     return getASTContext().getSourceManager();
79   }
80 
getLangOpts()81   const LangOptions &getLangOpts() const {
82     return getASTContext().getLangOpts();
83   }
84 
85   /// This function returns top-level decls present in the main file of the AST.
86   /// The result does not include the decls that come from the preamble.
87   /// (These should be const, but RecursiveASTVisitor requires Decl*).
88   ArrayRef<Decl *> getLocalTopLevelDecls();
89 
90   const std::vector<Diag> &getDiagnostics() const;
91 
92   /// Returns the estimated size of the AST and the accessory structures, in
93   /// bytes. Does not include the size of the preamble.
94   std::size_t getUsedBytes() const;
95   const IncludeStructure &getIncludeStructure() const;
96   const CanonicalIncludes &getCanonicalIncludes() const;
97 
98   /// Gets all macro references (definition, expansions) present in the main
99   /// file, including those in the preamble region.
100   const MainFileMacros &getMacros() const;
101   /// Tokens recorded while parsing the main file.
102   /// (!) does not have tokens from the preamble.
getTokens()103   const syntax::TokenBuffer &getTokens() const { return Tokens; }
104 
105   /// Returns the version of the ParseInputs this AST was built from.
version()106   llvm::StringRef version() const { return Version; }
107 
108   /// Returns the version of the ParseInputs used to build Preamble part of this
109   /// AST. Might be None if no Preamble is used.
110   llvm::Optional<llvm::StringRef> preambleVersion() const;
111 
112 private:
113   ParsedAST(llvm::StringRef Version,
114             std::shared_ptr<const PreambleData> Preamble,
115             std::unique_ptr<CompilerInstance> Clang,
116             std::unique_ptr<FrontendAction> Action, syntax::TokenBuffer Tokens,
117             MainFileMacros Macros, std::vector<Decl *> LocalTopLevelDecls,
118             std::vector<Diag> Diags, IncludeStructure Includes,
119             CanonicalIncludes CanonIncludes);
120 
121   std::string Version;
122   // In-memory preambles must outlive the AST, it is important that this member
123   // goes before Clang and Action.
124   std::shared_ptr<const PreambleData> Preamble;
125   // We store an "incomplete" FrontendAction (i.e. no EndSourceFile was called
126   // on it) and CompilerInstance used to run it. That way we don't have to do
127   // complex memory management of all Clang structures on our own. (They are
128   // stored in CompilerInstance and cleaned up by
129   // FrontendAction.EndSourceFile).
130   std::unique_ptr<CompilerInstance> Clang;
131   std::unique_ptr<FrontendAction> Action;
132   /// Tokens recorded after the preamble finished.
133   ///   - Includes all spelled tokens for the main file.
134   ///   - Includes expanded tokens produced **after** preabmle.
135   ///   - Does not have spelled or expanded tokens for files from preamble.
136   syntax::TokenBuffer Tokens;
137 
138   /// All macro definitions and expansions in the main file.
139   MainFileMacros Macros;
140   // Data, stored after parsing.
141   std::vector<Diag> Diags;
142   // Top-level decls inside the current file. Not that this does not include
143   // top-level decls from the preamble.
144   std::vector<Decl *> LocalTopLevelDecls;
145   IncludeStructure Includes;
146   CanonicalIncludes CanonIncludes;
147 };
148 
149 /// For testing/debugging purposes. Note that this method deserializes all
150 /// unserialized Decls, so use with care.
151 void dumpAST(ParsedAST &AST, llvm::raw_ostream &OS);
152 
153 } // namespace clangd
154 } // namespace clang
155 
156 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_PARSEDAST_H
157