ASTUnit.h source code [clang_source_code/include/clang/Frontend/ASTUnit.h]

1	//===- ASTUnit.h - ASTUnit utility ------------------------------- 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	// ASTUnit utility class.
10	//
11	//===----------------------------------------------------------------------===//
12
13	#ifndef LLVM_CLANG_FRONTEND_ASTUNIT_H
14	#define LLVM_CLANG_FRONTEND_ASTUNIT_H
15
16	#include "clang-c/Index.h"
17	#include "clang/AST/ASTContext.h"
18	#include "clang/Basic/Diagnostic.h"
19	#include "clang/Basic/FileSystemOptions.h"
20	#include "clang/Basic/LLVM.h"
21	#include "clang/Basic/LangOptions.h"
22	#include "clang/Basic/SourceLocation.h"
23	#include "clang/Basic/SourceManager.h"
24	#include "clang/Basic/TargetOptions.h"
25	#include "clang/Lex/HeaderSearchOptions.h"
26	#include "clang/Lex/ModuleLoader.h"
27	#include "clang/Lex/PreprocessingRecord.h"
28	#include "clang/Sema/CodeCompleteConsumer.h"
29	#include "clang/Serialization/ASTBitCodes.h"
30	#include "clang/Frontend/PrecompiledPreamble.h"
31	#include "llvm/ADT/ArrayRef.h"
32	#include "llvm/ADT/DenseMap.h"
33	#include "llvm/ADT/IntrusiveRefCntPtr.h"
34	#include "llvm/ADT/None.h"
35	#include "llvm/ADT/Optional.h"
36	#include "llvm/ADT/STLExtras.h"
37	#include "llvm/ADT/SmallVector.h"
38	#include "llvm/ADT/StringMap.h"
39	#include "llvm/ADT/StringRef.h"
40	#include "llvm/ADT/iterator_range.h"
41	#include <cassert>
42	#include <cstddef>
43	#include <cstdint>
44	#include <memory>
45	#include <string>
46	#include <utility>
47	#include <vector>
48
49	namespace llvm {
50
51	class MemoryBuffer;
52
53	namespace vfs {
54
55	class FileSystem;
56
57	} // namespace vfs
58	} // namespace llvm
59
60	namespace clang {
61
62	class ASTContext;
63	class ASTDeserializationListener;
64	class ASTMutationListener;
65	class ASTReader;
66	class CompilerInstance;
67	class CompilerInvocation;
68	class Decl;
69	class FileEntry;
70	class FileManager;
71	class FrontendAction;
72	class HeaderSearch;
73	class InputKind;
74	class InMemoryModuleCache;
75	class PCHContainerOperations;
76	class PCHContainerReader;
77	class Preprocessor;
78	class PreprocessorOptions;
79	class Sema;
80	class TargetInfo;
81
82	/// \brief Enumerates the available scopes for skipping function bodies.
83	enum class SkipFunctionBodiesScope { None, Preamble, PreambleAndMainFile };
84
85	/// Utility class for loading a ASTContext from an AST file.
86	class ASTUnit {
87	public:
88	struct StandaloneFixIt {
89	std::pair<unsigned, unsigned> RemoveRange;
90	std::pair<unsigned, unsigned> InsertFromRange;
91	std::string CodeToInsert;
92	bool BeforePreviousInsertions;
93	};
94
95	struct StandaloneDiagnostic {
96	unsigned ID;
97	DiagnosticsEngine::Level Level;
98	std::string Message;
99	std::string Filename;
100	unsigned LocOffset;
101	std::vector<std::pair<unsigned, unsigned>> Ranges;
102	std::vector<StandaloneFixIt> FixIts;
103	};
104
105	private:
106	std::shared_ptr<LangOptions> LangOpts;
107	IntrusiveRefCntPtr<DiagnosticsEngine> Diagnostics;
108	IntrusiveRefCntPtr<FileManager> FileMgr;
109	IntrusiveRefCntPtr<SourceManager> SourceMgr;
110	IntrusiveRefCntPtr<InMemoryModuleCache> ModuleCache;
111	std::unique_ptr<HeaderSearch> HeaderInfo;
112	IntrusiveRefCntPtr<TargetInfo> Target;
113	std::shared_ptr<Preprocessor> PP;
114	IntrusiveRefCntPtr<ASTContext> Ctx;
115	std::shared_ptr<TargetOptions> TargetOpts;
116	std::shared_ptr<HeaderSearchOptions> HSOpts;
117	std::shared_ptr<PreprocessorOptions> PPOpts;
118	IntrusiveRefCntPtr<ASTReader> Reader;
119	bool HadModuleLoaderFatalFailure = false;
120
121	struct ASTWriterData;
122	std::unique_ptr<ASTWriterData> WriterData;
123
124	FileSystemOptions FileSystemOpts;
125
126	/// The AST consumer that received information about the translation
127	/// unit as it was parsed or loaded.
128	std::unique_ptr<ASTConsumer> Consumer;
129
130	/// The semantic analysis object used to type-check the translation
131	/// unit.
132	std::unique_ptr<Sema> TheSema;
133
134	/// Optional owned invocation, just used to make the invocation used in
135	/// LoadFromCommandLine available.
136	std::shared_ptr<CompilerInvocation> Invocation;
137
138	/// Fake module loader: the AST unit doesn't need to load any modules.
139	TrivialModuleLoader ModuleLoader;
140
141	// OnlyLocalDecls - when true, walking this AST should only visit declarations
142	// that come from the AST itself, not from included precompiled headers.
143	// FIXME: This is temporary; eventually, CIndex will always do this.
144	bool OnlyLocalDecls = false;
145
146	/// Whether to capture any diagnostics produced.
147	bool CaptureDiagnostics = false;
148
149	/// Track whether the main file was loaded from an AST or not.
150	bool MainFileIsAST;
151
152	/// What kind of translation unit this AST represents.
153	TranslationUnitKind TUKind = TU_Complete;
154
155	/// Whether we should time each operation.
156	bool WantTiming;
157
158	/// Whether the ASTUnit should delete the remapped buffers.
159	bool OwnsRemappedFileBuffers = true;
160
161	/// Track the top-level decls which appeared in an ASTUnit which was loaded
162	/// from a source file.
163	//
164	// FIXME: This is just an optimization hack to avoid deserializing large parts
165	// of a PCH file when using the Index library on an ASTUnit loaded from
166	// source. In the long term we should make the Index library use efficient and
167	// more scalable search mechanisms.
168	std::vector<Decl*> TopLevelDecls;
169
170	/// Sorted (by file offset) vector of pairs of file offset/Decl.
171	using LocDeclsTy = SmallVector<std::pair<unsigned, Decl *>, 64>;
172	using FileDeclsTy = llvm::DenseMap<FileID, LocDeclsTy *>;
173
174	/// Map from FileID to the file-level declarations that it contains.
175	/// The files and decls are only local (and non-preamble) ones.
176	FileDeclsTy FileDecls;
177
178	/// The name of the original source file used to generate this ASTUnit.
179	std::string OriginalSourceFile;
180
181	/// The set of diagnostics produced when creating the preamble.
182	SmallVector<StandaloneDiagnostic, 4> PreambleDiagnostics;
183
184	/// The set of diagnostics produced when creating this
185	/// translation unit.
186	SmallVector<StoredDiagnostic, 4> StoredDiagnostics;
187
188	/// The set of diagnostics produced when failing to parse, e.g. due
189	/// to failure to load the PCH.
190	SmallVector<StoredDiagnostic, 4> FailedParseDiagnostics;
191
192	/// The number of stored diagnostics that come from the driver
193	/// itself.
194	///
195	/// Diagnostics that come from the driver are retained from one parse to
196	/// the next.
197	unsigned NumStoredDiagnosticsFromDriver = 0;
198
199	/// Counter that determines when we want to try building a
200	/// precompiled preamble.
201	///
202	/// If zero, we will never build a precompiled preamble. Otherwise,
203	/// it's treated as a counter that decrements each time we reparse
204	/// without the benefit of a precompiled preamble. When it hits 1,
205	/// we'll attempt to rebuild the precompiled header. This way, if
206	/// building the precompiled preamble fails, we won't try again for
207	/// some number of calls.
208	unsigned PreambleRebuildCounter = 0;
209
210	/// Cache pairs "filename - source location"
211	///
212	/// Cache contains only source locations from preamble so it is
213	/// guaranteed that they stay valid when the SourceManager is recreated.
214	/// This cache is used when loading preamble to increase performance
215	/// of that loading. It must be cleared when preamble is recreated.
216	llvm::StringMap<SourceLocation> PreambleSrcLocCache;
217
218	/// The contents of the preamble.
219	llvm::Optional<PrecompiledPreamble> Preamble;
220
221	/// When non-NULL, this is the buffer used to store the contents of
222	/// the main file when it has been padded for use with the precompiled
223	/// preamble.
224	std::unique_ptr<llvm::MemoryBuffer> SavedMainFileBuffer;
225
226	/// The number of warnings that occurred while parsing the preamble.
227	///
228	/// This value will be used to restore the state of the \c DiagnosticsEngine
229	/// object when re-using the precompiled preamble. Note that only the
230	/// number of warnings matters, since we will not save the preamble
231	/// when any errors are present.
232	unsigned NumWarningsInPreamble = 0;
233
234	/// A list of the serialization ID numbers for each of the top-level
235	/// declarations parsed within the precompiled preamble.
236	std::vector<serialization::DeclID> TopLevelDeclsInPreamble;
237
238	/// Whether we should be caching code-completion results.
239	bool ShouldCacheCodeCompletionResults : 1;
240
241	/// Whether to include brief documentation within the set of code
242	/// completions cached.
243	bool IncludeBriefCommentsInCodeCompletion : 1;
244
245	/// True if non-system source files should be treated as volatile
246	/// (likely to change while trying to use them).
247	bool UserFilesAreVolatile : 1;
248
249	static void ConfigureDiags(IntrusiveRefCntPtr<DiagnosticsEngine> Diags,
250	ASTUnit &AST, bool CaptureDiagnostics);
251
252	void TranslateStoredDiagnostics(FileManager &FileMgr,
253	SourceManager &SrcMan,
254	const SmallVectorImpl<StandaloneDiagnostic> &Diags,
255	SmallVectorImpl<StoredDiagnostic> &Out);
256
257	void clearFileLevelDecls();
258
259	public:
260	/// A cached code-completion result, which may be introduced in one of
261	/// many different contexts.
262	struct CachedCodeCompletionResult {
263	/// The code-completion string corresponding to this completion
264	/// result.
265	CodeCompletionString *Completion;
266
267	/// A bitmask that indicates which code-completion contexts should
268	/// contain this completion result.
269	///
270	/// The bits in the bitmask correspond to the values of
271	/// CodeCompleteContext::Kind. To map from a completion context kind to a
272	/// bit, shift 1 by that number of bits. Many completions can occur in
273	/// several different contexts.
274	uint64_t ShowInContexts;
275
276	/// The priority given to this code-completion result.
277	unsigned Priority;
278
279	/// The libclang cursor kind corresponding to this code-completion
280	/// result.
281	CXCursorKind Kind;
282
283	/// The availability of this code-completion result.
284	CXAvailabilityKind Availability;
285
286	/// The simplified type class for a non-macro completion result.
287	SimplifiedTypeClass TypeClass;
288
289	/// The type of a non-macro completion result, stored as a unique
290	/// integer used by the string map of cached completion types.
291	///
292	/// This value will be zero if the type is not known, or a unique value
293	/// determined by the formatted type string. Se \c CachedCompletionTypes
294	/// for more information.
295	unsigned Type;
296	};
297
298	/// Retrieve the mapping from formatted type names to unique type
299	/// identifiers.
300	llvm::StringMap<unsigned> &getCachedCompletionTypes() {
301	return CachedCompletionTypes;
302	}
303
304	/// Retrieve the allocator used to cache global code completions.
305	std::shared_ptr<GlobalCodeCompletionAllocator>
306	getCachedCompletionAllocator() {
307	return CachedCompletionAllocator;
308	}
309
310	CodeCompletionTUInfo &getCodeCompletionTUInfo() {
311	if (!CCTUInfo)
312	CCTUInfo = llvm::make_unique<CodeCompletionTUInfo>(
313	std::make_shared<GlobalCodeCompletionAllocator>());
314	return *CCTUInfo;
315	}
316
317	private:
318	/// Allocator used to store cached code completions.
319	std::shared_ptr<GlobalCodeCompletionAllocator> CachedCompletionAllocator;
320
321	std::unique_ptr<CodeCompletionTUInfo> CCTUInfo;
322
323	/// The set of cached code-completion results.
324	std::vector<CachedCodeCompletionResult> CachedCompletionResults;
325
326	/// A mapping from the formatted type name to a unique number for that
327	/// type, which is used for type equality comparisons.
328	llvm::StringMap<unsigned> CachedCompletionTypes;
329
330	/// A string hash of the top-level declaration and macro definition
331	/// names processed the last time that we reparsed the file.
332	///
333	/// This hash value is used to determine when we need to refresh the
334	/// global code-completion cache.
335	unsigned CompletionCacheTopLevelHashValue = 0;
336
337	/// A string hash of the top-level declaration and macro definition
338	/// names processed the last time that we reparsed the precompiled preamble.
339	///
340	/// This hash value is used to determine when we need to refresh the
341	/// global code-completion cache after a rebuild of the precompiled preamble.
342	unsigned PreambleTopLevelHashValue = 0;
343
344	/// The current hash value for the top-level declaration and macro
345	/// definition names
346	unsigned CurrentTopLevelHashValue = 0;
347
348	/// Bit used by CIndex to mark when a translation unit may be in an
349	/// inconsistent state, and is not safe to free.
350	unsigned UnsafeToFree : 1;
351
352	/// \brief Enumerator specifying the scope for skipping function bodies.
353	SkipFunctionBodiesScope SkipFunctionBodies = SkipFunctionBodiesScope::None;
354
355	/// Cache any "global" code-completion results, so that we can avoid
356	/// recomputing them with each completion.
357	void CacheCodeCompletionResults();
358
359	/// Clear out and deallocate
360	void ClearCachedCompletionResults();
361
362	explicit ASTUnit(bool MainFileIsAST);
363
364	bool Parse(std::shared_ptr<PCHContainerOperations> PCHContainerOps,
365	std::unique_ptr<llvm::MemoryBuffer> OverrideMainBuffer,
366	IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS);
367
368	std::unique_ptr<llvm::MemoryBuffer> getMainBufferWithPrecompiledPreamble(
369	std::shared_ptr<PCHContainerOperations> PCHContainerOps,
370	CompilerInvocation &PreambleInvocationIn,
371	IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS, bool AllowRebuild = true,
372	unsigned MaxLines = 0);
373	void RealizeTopLevelDeclsFromPreamble();
374
375	/// Transfers ownership of the objects (like SourceManager) from
376	/// \param CI to this ASTUnit.
377	void transferASTDataFromCompilerInstance(CompilerInstance &CI);
378
379	/// Allows us to assert that ASTUnit is not being used concurrently,
380	/// which is not supported.
381	///
382	/// Clients should create instances of the ConcurrencyCheck class whenever
383	/// using the ASTUnit in a way that isn't intended to be concurrent, which is
384	/// just about any usage.
385	/// Becomes a noop in release mode; only useful for debug mode checking.
386	class ConcurrencyState {
387	void *Mutex; // a llvm::sys::MutexImpl in debug;
388
389	public:
390	ConcurrencyState();
391	~ConcurrencyState();
392
393	void start();
394	void finish();
395	};
396	ConcurrencyState ConcurrencyCheckValue;
397
398	public:
399	friend class ConcurrencyCheck;
400
401	class ConcurrencyCheck {
402	ASTUnit &Self;
403
404	public:
405	explicit ConcurrencyCheck(ASTUnit &Self) : Self(Self) {
406	Self.ConcurrencyCheckValue.start();
407	}
408
409	~ConcurrencyCheck() {
410	Self.ConcurrencyCheckValue.finish();
411	}
412	};
413
414	ASTUnit(const ASTUnit &) = delete;
415	ASTUnit &operator=(const ASTUnit &) = delete;
416	~ASTUnit();
417
418	bool isMainFileAST() const { return MainFileIsAST; }
419
420	bool isUnsafeToFree() const { return UnsafeToFree; }
421	void setUnsafeToFree(bool Value) { UnsafeToFree = Value; }
422
423	const DiagnosticsEngine &getDiagnostics() const { return *Diagnostics; }
424	DiagnosticsEngine &getDiagnostics() { return *Diagnostics; }
425
426	const SourceManager &getSourceManager() const { return *SourceMgr; }
427	SourceManager &getSourceManager() { return *SourceMgr; }
428
429	const Preprocessor &getPreprocessor() const { return *PP; }
430	Preprocessor &getPreprocessor() { return *PP; }
431	std::shared_ptr<Preprocessor> getPreprocessorPtr() const { return PP; }
432
433	const ASTContext &getASTContext() const { return *Ctx; }
434	ASTContext &getASTContext() { return *Ctx; }
435
436	void setASTContext(ASTContext *ctx) { Ctx = ctx; }
437	void setPreprocessor(std::shared_ptr<Preprocessor> pp);
438
439	/// Enable source-range based diagnostic messages.
440	///
441	/// If diagnostic messages with source-range information are to be expected
442	/// and AST comes not from file (e.g. after LoadFromCompilerInvocation) this
443	/// function has to be called.
444	/// The function is to be called only once and the AST should be associated
445	/// with the same source file afterwards.
446	void enableSourceFileDiagnostics();
447
448	bool hasSema() const { return (bool)TheSema; }
449
450	Sema &getSema() const {
451	(0) . __assert_fail ("TheSema && \"ASTUnit does not have a Sema object!\"", "/home/seafit/code_projects/clang_source/clang/include/clang/Frontend/ASTUnit.h", 451, __PRETTY_FUNCTION__))" file_link="../../../../include/assert.h.html#88" macro="true">assert(TheSema && "ASTUnit does not have a Sema object!");
452	return *TheSema;
453	}
454
455	const LangOptions &getLangOpts() const {
456	(0) . __assert_fail ("LangOpts && \"ASTUnit does not have language options\"", "/home/seafit/code_projects/clang_source/clang/include/clang/Frontend/ASTUnit.h", 456, __PRETTY_FUNCTION__))" file_link="../../../../include/assert.h.html#88" macro="true">assert(LangOpts && "ASTUnit does not have language options");
457	return *LangOpts;
458	}
459
460	const HeaderSearchOptions &getHeaderSearchOpts() const {
461	(0) . __assert_fail ("HSOpts && \"ASTUnit does not have header search options\"", "/home/seafit/code_projects/clang_source/clang/include/clang/Frontend/ASTUnit.h", 461, __PRETTY_FUNCTION__))" file_link="../../../../include/assert.h.html#88" macro="true">assert(HSOpts && "ASTUnit does not have header search options");
462	return *HSOpts;
463	}
464
465	const PreprocessorOptions &getPreprocessorOpts() const {
466	(0) . __assert_fail ("PPOpts && \"ASTUnit does not have preprocessor options\"", "/home/seafit/code_projects/clang_source/clang/include/clang/Frontend/ASTUnit.h", 466, __PRETTY_FUNCTION__))" file_link="../../../../include/assert.h.html#88" macro="true">assert(PPOpts && "ASTUnit does not have preprocessor options");
467	return *PPOpts;
468	}
469
470	const FileManager &getFileManager() const { return *FileMgr; }
471	FileManager &getFileManager() { return *FileMgr; }
472
473	const FileSystemOptions &getFileSystemOpts() const { return FileSystemOpts; }
474
475	IntrusiveRefCntPtr<ASTReader> getASTReader() const;
476
477	StringRef getOriginalSourceFileName() const {
478	return OriginalSourceFile;
479	}
480
481	ASTMutationListener *getASTMutationListener();
482	ASTDeserializationListener *getDeserializationListener();
483
484	bool getOnlyLocalDecls() const { return OnlyLocalDecls; }
485
486	bool getOwnsRemappedFileBuffers() const { return OwnsRemappedFileBuffers; }
487	void setOwnsRemappedFileBuffers(bool val) { OwnsRemappedFileBuffers = val; }
488
489	StringRef getMainFileName() const;
490
491	/// If this ASTUnit came from an AST file, returns the filename for it.
492	StringRef getASTFileName() const;
493
494	using top_level_iterator = std::vector<Decl *>::iterator;
495
496	top_level_iterator top_level_begin() {
497	(0) . __assert_fail ("!isMainFileAST() && \"Invalid call for AST based ASTUnit!\"", "/home/seafit/code_projects/clang_source/clang/include/clang/Frontend/ASTUnit.h", 497, __PRETTY_FUNCTION__))" file_link="../../../../include/assert.h.html#88" macro="true">assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
498	if (!TopLevelDeclsInPreamble.empty())
499	RealizeTopLevelDeclsFromPreamble();
500	return TopLevelDecls.begin();
501	}
502
503	top_level_iterator top_level_end() {
504	(0) . __assert_fail ("!isMainFileAST() && \"Invalid call for AST based ASTUnit!\"", "/home/seafit/code_projects/clang_source/clang/include/clang/Frontend/ASTUnit.h", 504, __PRETTY_FUNCTION__))" file_link="../../../../include/assert.h.html#88" macro="true">assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
505	if (!TopLevelDeclsInPreamble.empty())
506	RealizeTopLevelDeclsFromPreamble();
507	return TopLevelDecls.end();
508	}
509
510	std::size_t top_level_size() const {
511	(0) . __assert_fail ("!isMainFileAST() && \"Invalid call for AST based ASTUnit!\"", "/home/seafit/code_projects/clang_source/clang/include/clang/Frontend/ASTUnit.h", 511, __PRETTY_FUNCTION__))" file_link="../../../../include/assert.h.html#88" macro="true">assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
512	return TopLevelDeclsInPreamble.size() + TopLevelDecls.size();
513	}
514
515	bool top_level_empty() const {
516	(0) . __assert_fail ("!isMainFileAST() && \"Invalid call for AST based ASTUnit!\"", "/home/seafit/code_projects/clang_source/clang/include/clang/Frontend/ASTUnit.h", 516, __PRETTY_FUNCTION__))" file_link="../../../../include/assert.h.html#88" macro="true">assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
517	return TopLevelDeclsInPreamble.empty() && TopLevelDecls.empty();
518	}
519
520	/// Add a new top-level declaration.
521	void addTopLevelDecl(Decl *D) {
522	TopLevelDecls.push_back(D);
523	}
524
525	/// Add a new local file-level declaration.
526	void addFileLevelDecl(Decl *D);
527
528	/// Get the decls that are contained in a file in the Offset/Length
529	/// range. \p Length can be 0 to indicate a point at \p Offset instead of
530	/// a range.
531	void findFileRegionDecls(FileID File, unsigned Offset, unsigned Length,
532	SmallVectorImpl<Decl *> &Decls);
533
534	/// Retrieve a reference to the current top-level name hash value.
535	///
536	/// Note: This is used internally by the top-level tracking action
537	unsigned &getCurrentTopLevelHashValue() { return CurrentTopLevelHashValue; }
538
539	/// Get the source location for the given file:line:col triplet.
540	///
541	/// The difference with SourceManager::getLocation is that this method checks
542	/// whether the requested location points inside the precompiled preamble
543	/// in which case the returned source location will be a "loaded" one.
544	SourceLocation getLocation(const FileEntry *File,
545	unsigned Line, unsigned Col) const;
546
547	/// Get the source location for the given file:offset pair.
548	SourceLocation getLocation(const FileEntry *File, unsigned Offset) const;
549
550	/// If \p Loc is a loaded location from the preamble, returns
551	/// the corresponding local location of the main file, otherwise it returns
552	/// \p Loc.
553	SourceLocation mapLocationFromPreamble(SourceLocation Loc) const;
554
555	/// If \p Loc is a local location of the main file but inside the
556	/// preamble chunk, returns the corresponding loaded location from the
557	/// preamble, otherwise it returns \p Loc.
558	SourceLocation mapLocationToPreamble(SourceLocation Loc) const;
559
560	bool isInPreambleFileID(SourceLocation Loc) const;
561	bool isInMainFileID(SourceLocation Loc) const;
562	SourceLocation getStartOfMainFileID() const;
563	SourceLocation getEndOfPreambleFileID() const;
564
565	/// \see mapLocationFromPreamble.
566	SourceRange mapRangeFromPreamble(SourceRange R) const {
567	return SourceRange(mapLocationFromPreamble(R.getBegin()),
568	mapLocationFromPreamble(R.getEnd()));
569	}
570
571	/// \see mapLocationToPreamble.
572	SourceRange mapRangeToPreamble(SourceRange R) const {
573	return SourceRange(mapLocationToPreamble(R.getBegin()),
574	mapLocationToPreamble(R.getEnd()));
575	}
576
577	// Retrieve the diagnostics associated with this AST
578	using stored_diag_iterator = StoredDiagnostic *;
579	using stored_diag_const_iterator = const StoredDiagnostic *;
580
581	stored_diag_const_iterator stored_diag_begin() const {
582	return StoredDiagnostics.begin();
583	}
584
585	stored_diag_iterator stored_diag_begin() {
586	return StoredDiagnostics.begin();
587	}
588
589	stored_diag_const_iterator stored_diag_end() const {
590	return StoredDiagnostics.end();
591	}
592
593	stored_diag_iterator stored_diag_end() {
594	return StoredDiagnostics.end();
595	}
596
597	unsigned stored_diag_size() const { return StoredDiagnostics.size(); }
598
599	stored_diag_iterator stored_diag_afterDriver_begin() {
600	if (NumStoredDiagnosticsFromDriver > StoredDiagnostics.size())
601	NumStoredDiagnosticsFromDriver = 0;
602	return StoredDiagnostics.begin() + NumStoredDiagnosticsFromDriver;
603	}
604
605	using cached_completion_iterator =
606	std::vector<CachedCodeCompletionResult>::iterator;
607
608	cached_completion_iterator cached_completion_begin() {
609	return CachedCompletionResults.begin();
610	}
611
612	cached_completion_iterator cached_completion_end() {
613	return CachedCompletionResults.end();
614	}
615
616	unsigned cached_completion_size() const {
617	return CachedCompletionResults.size();
618	}
619
620	/// Returns an iterator range for the local preprocessing entities
621	/// of the local Preprocessor, if this is a parsed source file, or the loaded
622	/// preprocessing entities of the primary module if this is an AST file.
623	llvm::iterator_range<PreprocessingRecord::iterator>
624	getLocalPreprocessingEntities() const;
625
626	/// Type for a function iterating over a number of declarations.
627	/// \returns true to continue iteration and false to abort.
628	using DeclVisitorFn = bool ()(void context, const Decl *D);
629
630	/// Iterate over local declarations (locally parsed if this is a parsed
631	/// source file or the loaded declarations of the primary module if this is an
632	/// AST file).
633	/// \returns true if the iteration was complete or false if it was aborted.
634	bool visitLocalTopLevelDecls(void *context, DeclVisitorFn Fn);
635
636	/// Get the PCH file if one was included.
637	const FileEntry *getPCHFile();
638
639	/// Returns true if the ASTUnit was constructed from a serialized
640	/// module file.
641	bool isModuleFile() const;
642
643	std::unique_ptr<llvm::MemoryBuffer>
644	getBufferForFile(StringRef Filename, std::string *ErrorStr = nullptr);
645
646	/// Determine what kind of translation unit this AST represents.
647	TranslationUnitKind getTranslationUnitKind() const { return TUKind; }
648
649	/// Determine the input kind this AST unit represents.
650	InputKind getInputKind() const;
651
652	/// A mapping from a file name to the memory buffer that stores the
653	/// remapped contents of that file.
654	using RemappedFile = std::pair<std::string, llvm::MemoryBuffer *>;
655
656	/// Create a ASTUnit. Gets ownership of the passed CompilerInvocation.
657	static std::unique_ptr<ASTUnit>
658	create(std::shared_ptr<CompilerInvocation> CI,
659	IntrusiveRefCntPtr<DiagnosticsEngine> Diags, bool CaptureDiagnostics,
660	bool UserFilesAreVolatile);
661
662	enum WhatToLoad {
663	/// Load options and the preprocessor state.
664	LoadPreprocessorOnly,
665
666	/// Load the AST, but do not restore Sema state.
667	LoadASTOnly,
668
669	/// Load everything, including Sema.
670	LoadEverything
671	};
672
673	/// Create a ASTUnit from an AST file.
674	///
675	/// \param Filename - The AST file to load.
676	///
677	/// \param PCHContainerRdr - The PCHContainerOperations to use for loading and
678	/// creating modules.
679	/// \param Diags - The diagnostics engine to use for reporting errors; its
680	/// lifetime is expected to extend past that of the returned ASTUnit.
681	///
682	/// \returns - The initialized ASTUnit or null if the AST failed to load.
683	static std::unique_ptr<ASTUnit> LoadFromASTFile(
684	const std::string &Filename, const PCHContainerReader &PCHContainerRdr,
685	WhatToLoad ToLoad, IntrusiveRefCntPtr<DiagnosticsEngine> Diags,
686	const FileSystemOptions &FileSystemOpts, bool UseDebugInfo = false,
687	bool OnlyLocalDecls = false, ArrayRef<RemappedFile> RemappedFiles = None,
688	bool CaptureDiagnostics = false, bool AllowPCHWithCompilerErrors = false,
689	bool UserFilesAreVolatile = false);
690
691	private:
692	/// Helper function for \c LoadFromCompilerInvocation() and
693	/// \c LoadFromCommandLine(), which loads an AST from a compiler invocation.
694	///
695	/// \param PrecompilePreambleAfterNParses After how many parses the preamble
696	/// of this translation unit should be precompiled, to improve the performance
697	/// of reparsing. Set to zero to disable preambles.
698	///
699	/// \param VFS - A llvm::vfs::FileSystem to be used for all file accesses.
700	/// Note that preamble is saved to a temporary directory on a RealFileSystem,
701	/// so in order for it to be loaded correctly, VFS should have access to
702	/// it(i.e., be an overlay over RealFileSystem).
703	///
704	/// \returns \c true if a catastrophic failure occurred (which means that the
705	/// \c ASTUnit itself is invalid), or \c false otherwise.
706	bool LoadFromCompilerInvocation(
707	std::shared_ptr<PCHContainerOperations> PCHContainerOps,
708	unsigned PrecompilePreambleAfterNParses,
709	IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS);
710
711	public:
712	/// Create an ASTUnit from a source file, via a CompilerInvocation
713	/// object, by invoking the optionally provided ASTFrontendAction.
714	///
715	/// \param CI - The compiler invocation to use; it must have exactly one input
716	/// source file. The ASTUnit takes ownership of the CompilerInvocation object.
717	///
718	/// \param PCHContainerOps - The PCHContainerOperations to use for loading and
719	/// creating modules.
720	///
721	/// \param Diags - The diagnostics engine to use for reporting errors; its
722	/// lifetime is expected to extend past that of the returned ASTUnit.
723	///
724	/// \param Action - The ASTFrontendAction to invoke. Its ownership is not
725	/// transferred.
726	///
727	/// \param Unit - optionally an already created ASTUnit. Its ownership is not
728	/// transferred.
729	///
730	/// \param Persistent - if true the returned ASTUnit will be complete.
731	/// false means the caller is only interested in getting info through the
732	/// provided \see Action.
733	///
734	/// \param ErrAST - If non-null and parsing failed without any AST to return
735	/// (e.g. because the PCH could not be loaded), this accepts the ASTUnit
736	/// mainly to allow the caller to see the diagnostics.
737	/// This will only receive an ASTUnit if a new one was created. If an already
738	/// created ASTUnit was passed in \p Unit then the caller can check that.
739	///
740	static ASTUnit *LoadFromCompilerInvocationAction(
741	std::shared_ptr<CompilerInvocation> CI,
742	std::shared_ptr<PCHContainerOperations> PCHContainerOps,
743	IntrusiveRefCntPtr<DiagnosticsEngine> Diags,
744	FrontendAction Action = nullptr, ASTUnit Unit = nullptr,
745	bool Persistent = true, StringRef ResourceFilesPath = StringRef(),
746	bool OnlyLocalDecls = false, bool CaptureDiagnostics = false,
747	unsigned PrecompilePreambleAfterNParses = 0,
748	bool CacheCodeCompletionResults = false,
749	bool IncludeBriefCommentsInCodeCompletion = false,
750	bool UserFilesAreVolatile = false,
751	std::unique_ptr<ASTUnit> *ErrAST = nullptr);
752
753	/// LoadFromCompilerInvocation - Create an ASTUnit from a source file, via a
754	/// CompilerInvocation object.
755	///
756	/// \param CI - The compiler invocation to use; it must have exactly one input
757	/// source file. The ASTUnit takes ownership of the CompilerInvocation object.
758	///
759	/// \param PCHContainerOps - The PCHContainerOperations to use for loading and
760	/// creating modules.
761	///
762	/// \param Diags - The diagnostics engine to use for reporting errors; its
763	/// lifetime is expected to extend past that of the returned ASTUnit.
764	//
765	// FIXME: Move OnlyLocalDecls, UseBumpAllocator to setters on the ASTUnit, we
766	// shouldn't need to specify them at construction time.
767	static std::unique_ptr<ASTUnit> LoadFromCompilerInvocation(
768	std::shared_ptr<CompilerInvocation> CI,
769	std::shared_ptr<PCHContainerOperations> PCHContainerOps,
770	IntrusiveRefCntPtr<DiagnosticsEngine> Diags, FileManager *FileMgr,
771	bool OnlyLocalDecls = false, bool CaptureDiagnostics = false,
772	unsigned PrecompilePreambleAfterNParses = 0,
773	TranslationUnitKind TUKind = TU_Complete,
774	bool CacheCodeCompletionResults = false,
775	bool IncludeBriefCommentsInCodeCompletion = false,
776	bool UserFilesAreVolatile = false);
777
778	/// LoadFromCommandLine - Create an ASTUnit from a vector of command line
779	/// arguments, which must specify exactly one source file.
780	///
781	/// \param ArgBegin - The beginning of the argument vector.
782	///
783	/// \param ArgEnd - The end of the argument vector.
784	///
785	/// \param PCHContainerOps - The PCHContainerOperations to use for loading and
786	/// creating modules.
787	///
788	/// \param Diags - The diagnostics engine to use for reporting errors; its
789	/// lifetime is expected to extend past that of the returned ASTUnit.
790	///
791	/// \param ResourceFilesPath - The path to the compiler resource files.
792	///
793	/// \param ModuleFormat - If provided, uses the specific module format.
794	///
795	/// \param ErrAST - If non-null and parsing failed without any AST to return
796	/// (e.g. because the PCH could not be loaded), this accepts the ASTUnit
797	/// mainly to allow the caller to see the diagnostics.
798	///
799	/// \param VFS - A llvm::vfs::FileSystem to be used for all file accesses.
800	/// Note that preamble is saved to a temporary directory on a RealFileSystem,
801	/// so in order for it to be loaded correctly, VFS should have access to
802	/// it(i.e., be an overlay over RealFileSystem). RealFileSystem will be used
803	/// if \p VFS is nullptr.
804	///
805	// FIXME: Move OnlyLocalDecls, UseBumpAllocator to setters on the ASTUnit, we
806	// shouldn't need to specify them at construction time.
807	static ASTUnit *LoadFromCommandLine(
808	const char ArgBegin, const char ArgEnd,
809	std::shared_ptr<PCHContainerOperations> PCHContainerOps,
810	IntrusiveRefCntPtr<DiagnosticsEngine> Diags, StringRef ResourceFilesPath,
811	bool OnlyLocalDecls = false, bool CaptureDiagnostics = false,
812	ArrayRef<RemappedFile> RemappedFiles = None,
813	bool RemappedFilesKeepOriginalName = true,
814	unsigned PrecompilePreambleAfterNParses = 0,
815	TranslationUnitKind TUKind = TU_Complete,
816	bool CacheCodeCompletionResults = false,
817	bool IncludeBriefCommentsInCodeCompletion = false,
818	bool AllowPCHWithCompilerErrors = false,
819	SkipFunctionBodiesScope SkipFunctionBodies =
820	SkipFunctionBodiesScope::None,
821	bool SingleFileParse = false, bool UserFilesAreVolatile = false,
822	bool ForSerialization = false,
823	llvm::Optional<StringRef> ModuleFormat = llvm::None,
824	std::unique_ptr<ASTUnit> *ErrAST = nullptr,
825	IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS = nullptr);
826
827	/// Reparse the source files using the same command-line options that
828	/// were originally used to produce this translation unit.
829	///
830	/// \param VFS - A llvm::vfs::FileSystem to be used for all file accesses.
831	/// Note that preamble is saved to a temporary directory on a RealFileSystem,
832	/// so in order for it to be loaded correctly, VFS should give an access to
833	/// this(i.e. be an overlay over RealFileSystem).
834	/// FileMgr->getVirtualFileSystem() will be used if \p VFS is nullptr.
835	///
836	/// \returns True if a failure occurred that causes the ASTUnit not to
837	/// contain any translation-unit information, false otherwise.
838	bool Reparse(std::shared_ptr<PCHContainerOperations> PCHContainerOps,
839	ArrayRef<RemappedFile> RemappedFiles = None,
840	IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS = nullptr);
841
842	/// Free data that will be re-generated on the next parse.
843	///
844	/// Preamble-related data is not affected.
845	void ResetForParse();
846
847	/// Perform code completion at the given file, line, and
848	/// column within this translation unit.
849	///
850	/// \param File The file in which code completion will occur.
851	///
852	/// \param Line The line at which code completion will occur.
853	///
854	/// \param Column The column at which code completion will occur.
855	///
856	/// \param IncludeMacros Whether to include macros in the code-completion
857	/// results.
858	///
859	/// \param IncludeCodePatterns Whether to include code patterns (such as a
860	/// for loop) in the code-completion results.
861	///
862	/// \param IncludeBriefComments Whether to include brief documentation within
863	/// the set of code completions returned.
864	///
865	/// FIXME: The Diag, LangOpts, SourceMgr, FileMgr, StoredDiagnostics, and
866	/// OwnedBuffers parameters are all disgusting hacks. They will go away.
867	void CodeComplete(StringRef File, unsigned Line, unsigned Column,
868	ArrayRef<RemappedFile> RemappedFiles, bool IncludeMacros,
869	bool IncludeCodePatterns, bool IncludeBriefComments,
870	CodeCompleteConsumer &Consumer,
871	std::shared_ptr<PCHContainerOperations> PCHContainerOps,
872	DiagnosticsEngine &Diag, LangOptions &LangOpts,
873	SourceManager &SourceMgr, FileManager &FileMgr,
874	SmallVectorImpl<StoredDiagnostic> &StoredDiagnostics,
875	SmallVectorImpl<const llvm::MemoryBuffer *> &OwnedBuffers);
876
877	/// Save this translation unit to a file with the given name.
878	///
879	/// \returns true if there was a file error or false if the save was
880	/// successful.
881	bool Save(StringRef File);
882
883	/// Serialize this translation unit with the given output stream.
884	///
885	/// \returns True if an error occurred, false otherwise.
886	bool serialize(raw_ostream &OS);
887	};
888
889	} // namespace clang
890
891	#endif // LLVM_CLANG_FRONTEND_ASTUNIT_H
892