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