clang-tools  15.0.0git
SymbolCollector.h
Go to the documentation of this file.
1 //===--- SymbolCollector.h ---------------------------------------*- 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 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_SYMBOLCOLLECTOR_H
9 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_SYMBOLCOLLECTOR_H
10 
11 #include "CollectMacros.h"
13 #include "index/Ref.h"
14 #include "index/Relation.h"
15 #include "index/Symbol.h"
16 #include "index/SymbolID.h"
17 #include "index/SymbolOrigin.h"
18 #include "clang/AST/ASTContext.h"
19 #include "clang/AST/Decl.h"
20 #include "clang/Basic/SourceLocation.h"
21 #include "clang/Basic/SourceManager.h"
22 #include "clang/Index/IndexDataConsumer.h"
23 #include "clang/Index/IndexSymbol.h"
24 #include "clang/Sema/CodeCompleteConsumer.h"
25 #include "llvm/ADT/ArrayRef.h"
26 #include "llvm/ADT/DenseMap.h"
27 #include <functional>
28 
29 namespace clang {
30 namespace clangd {
31 
32 /// Collect declarations (symbols) from an AST.
33 /// It collects most declarations except:
34 /// - Implicit declarations
35 /// - Anonymous declarations (anonymous enum/class/struct, etc)
36 /// - Declarations in anonymous namespaces in headers
37 /// - Local declarations (in function bodies, blocks, etc)
38 /// - Template specializations
39 /// - Library-specific private declarations (e.g. private declaration generated
40 /// by protobuf compiler)
41 ///
42 /// References to main-file symbols are not collected.
43 ///
44 /// See also shouldCollectSymbol(...).
45 ///
46 /// Clients (e.g. clangd) can use SymbolCollector together with
47 /// index::indexTopLevelDecls to retrieve all symbols when the source file is
48 /// changed.
49 class SymbolCollector : public index::IndexDataConsumer {
50 public:
51  struct Options {
52  /// When symbol paths cannot be resolved to absolute paths (e.g. files in
53  /// VFS that does not have absolute path), combine the fallback directory
54  /// with symbols' paths to get absolute paths. This must be an absolute
55  /// path.
56  std::string FallbackDir;
57  bool CollectIncludePath = false;
58  /// If set, this is used to map symbol #include path to a potentially
59  /// different #include path.
60  const CanonicalIncludes *Includes = nullptr;
61  // Populate the Symbol.References field.
62  bool CountReferences = false;
63  /// The symbol ref kinds that will be collected.
64  /// If not set, SymbolCollector will not collect refs.
65  /// Note that references of namespace decls are not collected, as they
66  /// contribute large part of the index, and they are less useful compared
67  /// with other decls.
69  /// If set to true, SymbolCollector will collect all refs (from main file
70  /// and included headers); otherwise, only refs from main file will be
71  /// collected.
72  /// This flag is only meaningful when RefFilter is set.
73  bool RefsInHeaders = false;
74  // Every symbol collected will be stamped with this origin.
76  /// Collect macros.
77  /// Note that SymbolCollector must be run with preprocessor in order to
78  /// collect macros. For example, `indexTopLevelDecls` will not index any
79  /// macro even if this is true.
80  bool CollectMacro = false;
81  /// Collect symbols local to main-files, such as static functions, symbols
82  /// inside an anonymous namespace, function-local classes and its member
83  /// functions.
85  /// Collect references to main-file symbols.
86  bool CollectMainFileRefs = false;
87  /// Collect symbols with reserved names, like __Vector_base.
88  /// This does not currently affect macros (many like _WIN32 are important!)
89  bool CollectReserved = false;
90  /// If set to true, SymbolCollector will collect doc for all symbols.
91  /// Note that documents of symbols being indexed for completion will always
92  /// be collected regardless of this option.
93  bool StoreAllDocumentation = false;
94  /// If this is set, only collect symbols/references from a file if
95  /// `FileFilter(SM, FID)` is true. If not set, all files are indexed.
96  std::function<bool(const SourceManager &, FileID)> FileFilter = nullptr;
97  };
98 
101 
102  /// Returns true is \p ND should be collected.
103  static bool shouldCollectSymbol(const NamedDecl &ND, const ASTContext &ASTCtx,
104  const Options &Opts, bool IsMainFileSymbol);
105 
106  void initialize(ASTContext &Ctx) override;
107 
108  void setPreprocessor(std::shared_ptr<Preprocessor> PP) override {
109  this->PP = PP.get();
110  }
111  void setPreprocessor(Preprocessor &PP) { this->PP = &PP; }
112 
113  bool
114  handleDeclOccurrence(const Decl *D, index::SymbolRoleSet Roles,
115  ArrayRef<index::SymbolRelation> Relations,
116  SourceLocation Loc,
117  index::IndexDataConsumer::ASTNodeInfo ASTNode) override;
118 
119  bool handleMacroOccurrence(const IdentifierInfo *Name, const MacroInfo *MI,
120  index::SymbolRoleSet Roles,
121  SourceLocation Loc) override;
122 
123  void handleMacros(const MainFileMacros &MacroRefsToIndex);
124 
125  SymbolSlab takeSymbols() { return std::move(Symbols).build(); }
126  RefSlab takeRefs() { return std::move(Refs).build(); }
127  RelationSlab takeRelations() { return std::move(Relations).build(); }
128 
129  /// Returns true if we are interested in references and declarations from \p
130  /// FID. If this function return false, bodies of functions inside those files
131  /// will be skipped to decrease indexing time.
132  bool shouldIndexFile(FileID FID);
133 
134  void finish() override;
135 
136 private:
137  const Symbol *addDeclaration(const NamedDecl &, SymbolID,
138  bool IsMainFileSymbol);
139  void addDefinition(const NamedDecl &, const Symbol &DeclSymbol);
140  void processRelations(const NamedDecl &ND, const SymbolID &ID,
141  ArrayRef<index::SymbolRelation> Relations);
142 
143  llvm::Optional<SymbolLocation> getTokenLocation(SourceLocation TokLoc);
144 
145  llvm::Optional<std::string> getIncludeHeader(const Symbol &S, FileID);
146 
147  SymbolID getSymbolIDCached(const Decl *D);
148  SymbolID getSymbolIDCached(const llvm::StringRef MacroName,
149  const MacroInfo *MI, const SourceManager &SM);
150 
151  // All Symbols collected from the AST.
152  SymbolSlab::Builder Symbols;
153  // File IDs for Symbol.IncludeHeaders.
154  // The final spelling is calculated in finish().
155  llvm::DenseMap<SymbolID, FileID> IncludeFiles;
156  void setIncludeLocation(const Symbol &S, SourceLocation);
157  // Indexed macros, to be erased if they turned out to be include guards.
158  llvm::DenseSet<const IdentifierInfo *> IndexedMacros;
159  // All refs collected from the AST. It includes:
160  // 1) symbols declared in the preamble and referenced from the main file (
161  // which is not a header), or
162  // 2) symbols declared and referenced from the main file (which is a header)
163  RefSlab::Builder Refs;
164  // All relations collected from the AST.
165  RelationSlab::Builder Relations;
166  ASTContext *ASTCtx;
167  Preprocessor *PP = nullptr;
168  std::shared_ptr<GlobalCodeCompletionAllocator> CompletionAllocator;
169  std::unique_ptr<CodeCompletionTUInfo> CompletionTUInfo;
170  Options Opts;
171  struct SymbolRef {
172  SourceLocation Loc;
173  FileID FID;
174  index::SymbolRoleSet Roles;
175  const Decl *Container;
176  bool Spelled;
177  };
178  void addRef(SymbolID ID, const SymbolRef &SR);
179  // Symbols referenced from the current TU, flushed on finish().
180  llvm::DenseSet<SymbolID> ReferencedSymbols;
181  // Maps canonical declaration provided by clang to canonical declaration for
182  // an index symbol, if clangd prefers a different declaration than that
183  // provided by clang. For example, friend declaration might be considered
184  // canonical by clang but should not be considered canonical in the index
185  // unless it's a definition.
186  llvm::DenseMap<const Decl *, const Decl *> CanonicalDecls;
187  // Cache whether to index a file or not.
188  llvm::DenseMap<FileID, bool> FilesToIndexCache;
189  // Encapsulates calculations and caches around header paths, which headers
190  // to insert for which symbol, etc.
191  class HeaderFileURICache;
192  std::unique_ptr<HeaderFileURICache> HeaderFileURIs;
193  llvm::DenseMap<const Decl *, SymbolID> DeclToIDCache;
194  llvm::DenseMap<const MacroInfo *, SymbolID> MacroToIDCache;
195 };
196 
197 } // namespace clangd
198 } // namespace clang
199 
200 #endif
clang::clangd::SymbolCollector::setPreprocessor
void setPreprocessor(std::shared_ptr< Preprocessor > PP) override
Definition: SymbolCollector.h:108
Loc
SourceLocation Loc
Definition: KernelNameRestrictionCheck.cpp:45
SymbolID.h
SymbolOrigin.h
clang::clangd::SymbolCollector::Options::Origin
SymbolOrigin Origin
Definition: SymbolCollector.h:75
clang::clangd::SymbolCollector::Options::CollectMainFileSymbols
bool CollectMainFileSymbols
Collect symbols local to main-files, such as static functions, symbols inside an anonymous namespace,...
Definition: SymbolCollector.h:84
clang::clangd::RefKind::Unknown
@ Unknown
clang::clangd::SymbolCollector::handleMacros
void handleMacros(const MainFileMacros &MacroRefsToIndex)
Definition: SymbolCollector.cpp:643
clang::clangd::SymbolCollector::Options::CollectMainFileRefs
bool CollectMainFileRefs
Collect references to main-file symbols.
Definition: SymbolCollector.h:86
clang::clangd::SymbolCollector::Options::RefsInHeaders
bool RefsInHeaders
If set to true, SymbolCollector will collect all refs (from main file and included headers); otherwis...
Definition: SymbolCollector.h:73
clang::clangd::SymbolCollector::shouldCollectSymbol
static bool shouldCollectSymbol(const NamedDecl &ND, const ASTContext &ASTCtx, const Options &Opts, bool IsMainFileSymbol)
Returns true is ND should be collected.
Definition: SymbolCollector.cpp:466
clang::clangd::SymbolCollector::handleDeclOccurrence
bool handleDeclOccurrence(const Decl *D, index::SymbolRoleSet Roles, ArrayRef< index::SymbolRelation > Relations, SourceLocation Loc, index::IndexDataConsumer::ASTNodeInfo ASTNode) override
Definition: SymbolCollector.cpp:521
clang::clangd::RefKind
RefKind
Describes the kind of a cross-reference.
Definition: Ref.h:28
clang::clangd::RefSlab::Builder
RefSlab::Builder is a mutable container that can 'freeze' to RefSlab.
Definition: Ref.h:132
clang::clangd::SymbolCollector::shouldIndexFile
bool shouldIndexFile(FileID FID)
Returns true if we are interested in references and declarations from FID.
Definition: SymbolCollector.cpp:964
clang::clangd::SymbolCollector::Options::FileFilter
std::function< bool(const SourceManager &, FileID)> FileFilter
If this is set, only collect symbols/references from a file if FileFilter(SM, FID) is true.
Definition: SymbolCollector.h:96
clang::clangd::SymbolCollector::takeRelations
RelationSlab takeRelations()
Definition: SymbolCollector.h:127
Ctx
Context Ctx
Definition: TUScheduler.cpp:495
clang::clangd::SymbolCollector::setPreprocessor
void setPreprocessor(Preprocessor &PP)
Definition: SymbolCollector.h:111
clang::clangd::RelationSlab::Builder
RelationSlab::Builder is a mutable container that can 'freeze' to RelationSlab.
Definition: Relation.h:75
clang::clangd::SymbolCollector::finish
void finish() override
Definition: SymbolCollector.cpp:815
clang::clangd::RefSlab
An efficient structure of storing large set of symbol references in memory.
Definition: Ref.h:108
Relation.h
clang::clangd::SymbolCollector::Options::RefFilter
RefKind RefFilter
The symbol ref kinds that will be collected.
Definition: SymbolCollector.h:68
CanonicalIncludes.h
ns1::ns2::D
@ D
Definition: CategoricalFeature.h:3
Decl
const FunctionDecl * Decl
Definition: AvoidBindCheck.cpp:100
clang::clangd::CanonicalIncludes
Maps a definition location onto an #include file, based on a set of filename rules.
Definition: CanonicalIncludes.h:37
clang::clangd::RelationSlab
Definition: Relation.h:50
CollectMacros.h
clang::clangd::SymbolCollector::takeRefs
RefSlab takeRefs()
Definition: SymbolCollector.h:126
clang::clangd::MainFileMacros
Definition: CollectMacros.h:29
clang::clangd::SymbolCollector::Options::CollectMacro
bool CollectMacro
Collect macros.
Definition: SymbolCollector.h:80
clang::clangd::Symbol
The class presents a C++ symbol, e.g.
Definition: Symbol.h:36
clang::clangd::SymbolCollector::Options::Includes
const CanonicalIncludes * Includes
If set, this is used to map symbol #include path to a potentially different #include path.
Definition: SymbolCollector.h:60
clang::doc::SymbolID
std::array< uint8_t, 20 > SymbolID
Definition: Representation.h:30
Name
Token Name
Definition: MacroToEnumCheck.cpp:89
Symbol.h
clang::clangd::SymbolCollector::handleMacroOccurrence
bool handleMacroOccurrence(const IdentifierInfo *Name, const MacroInfo *MI, index::SymbolRoleSet Roles, SourceLocation Loc) override
Definition: SymbolCollector.cpp:687
clang::clangd::SymbolCollector::takeSymbols
SymbolSlab takeSymbols()
Definition: SymbolCollector.h:125
clang::clangd::RefKind::Spelled
@ Spelled
ID
static char ID
Definition: Logger.cpp:74
clang::clangd::SymbolCollector::initialize
void initialize(ASTContext &Ctx) override
Definition: SymbolCollector.cpp:457
clang::clangd::SymbolCollector
Collect declarations (symbols) from an AST.
Definition: SymbolCollector.h:49
Ref.h
clang::clangd::SymbolCollector::Options::CollectReserved
bool CollectReserved
Collect symbols with reserved names, like __Vector_base.
Definition: SymbolCollector.h:89
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
clang::clangd::SymbolOrigin
SymbolOrigin
Definition: SymbolOrigin.h:21
clang::clangd::SymbolCollector::Options::CountReferences
bool CountReferences
Definition: SymbolCollector.h:62
clang::clangd::SymbolCollector::Options
Definition: SymbolCollector.h:51
clang::clangd::SymbolCollector::Options::CollectIncludePath
bool CollectIncludePath
Definition: SymbolCollector.h:57
clang::clangd::SymbolSlab::Builder
SymbolSlab::Builder is a mutable container that can 'freeze' to SymbolSlab.
Definition: Symbol.h:200
clang::clangd::SymbolSlab
An immutable symbol container that stores a set of symbols.
Definition: Symbol.h:177
clang::clangd::SymbolCollector::Options::StoreAllDocumentation
bool StoreAllDocumentation
If set to true, SymbolCollector will collect doc for all symbols.
Definition: SymbolCollector.h:93
clang::clangd::SymbolID
Definition: SymbolID.h:32
clang::clangd::SymbolCollector::SymbolCollector
SymbolCollector(Options Opts)
Definition: SymbolCollector.cpp:454
clang::clangd::ASTNode
Simplified description of a clang AST node.
Definition: Protocol.h:1805
clang::clangd::SymbolCollector::Options::FallbackDir
std::string FallbackDir
When symbol paths cannot be resolved to absolute paths (e.g.
Definition: SymbolCollector.h:56
clang::clangd::SymbolOrigin::Unknown
@ Unknown
clang::clangd::SymbolCollector::~SymbolCollector
~SymbolCollector()