clang-tools  10.0.0svn
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_SYMBOL_COLLECTOR_H
9 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_SYMBOL_COLLECTOR_H
10 
11 #include "CanonicalIncludes.h"
12 #include "Index.h"
13 #include "SymbolOrigin.h"
14 #include "clang/AST/ASTContext.h"
15 #include "clang/AST/Decl.h"
16 #include "clang/Basic/SourceLocation.h"
17 #include "clang/Basic/SourceManager.h"
18 #include "clang/Index/IndexDataConsumer.h"
19 #include "clang/Index/IndexSymbol.h"
20 #include "clang/Sema/CodeCompleteConsumer.h"
21 #include "llvm/ADT/DenseMap.h"
22 #include "llvm/Support/Regex.h"
23 #include <functional>
24 
25 namespace clang {
26 namespace clangd {
27 
28 /// Collect declarations (symbols) from an AST.
29 /// It collects most declarations except:
30 /// - Implicit declarations
31 /// - Anonymous declarations (anonymous enum/class/struct, etc)
32 /// - Declarations in anonymous namespaces in headers
33 /// - Local declarations (in function bodies, blocks, etc)
34 /// - Template specializations
35 /// - Library-specific private declarations (e.g. private declaration generated
36 /// by protobuf compiler)
37 ///
38 /// References to main-file symbols are not collected.
39 ///
40 /// See also shouldCollectSymbol(...).
41 ///
42 /// Clients (e.g. clangd) can use SymbolCollector together with
43 /// index::indexTopLevelDecls to retrieve all symbols when the source file is
44 /// changed.
45 class SymbolCollector : public index::IndexDataConsumer {
46 public:
47  struct Options {
48  /// When symbol paths cannot be resolved to absolute paths (e.g. files in
49  /// VFS that does not have absolute path), combine the fallback directory
50  /// with symbols' paths to get absolute paths. This must be an absolute
51  /// path.
52  std::string FallbackDir;
53  bool CollectIncludePath = false;
54  /// If set, this is used to map symbol #include path to a potentially
55  /// different #include path.
56  const CanonicalIncludes *Includes = nullptr;
57  // Populate the Symbol.References field.
58  bool CountReferences = false;
59  /// The symbol ref kinds that will be collected.
60  /// If not set, SymbolCollector will not collect refs.
61  /// Note that references of namespace decls are not collected, as they
62  /// contribute large part of the index, and they are less useful compared
63  /// with other decls.
65  /// If set to true, SymbolCollector will collect all refs (from main file
66  /// and included headers); otherwise, only refs from main file will be
67  /// collected.
68  /// This flag is only meaningful when RefFilter is set.
69  bool RefsInHeaders = false;
70  // Every symbol collected will be stamped with this origin.
72  /// Collect macros.
73  /// Note that SymbolCollector must be run with preprocessor in order to
74  /// collect macros. For example, `indexTopLevelDecls` will not index any
75  /// macro even if this is true.
76  bool CollectMacro = false;
77  /// Collect symbols local to main-files, such as static functions
78  /// and symbols inside an anonymous namespace.
80  /// If set to true, SymbolCollector will collect doc for all symbols.
81  /// Note that documents of symbols being indexed for completion will always
82  /// be collected regardless of this option.
83  bool StoreAllDocumentation = false;
84  /// If this is set, only collect symbols/references from a file if
85  /// `FileFilter(SM, FID)` is true. If not set, all files are indexed.
86  std::function<bool(const SourceManager &, FileID)> FileFilter = nullptr;
87  };
88 
90 
91  /// Returns true is \p ND should be collected.
92  static bool shouldCollectSymbol(const NamedDecl &ND, const ASTContext &ASTCtx,
93  const Options &Opts, bool IsMainFileSymbol);
94 
95  void initialize(ASTContext &Ctx) override;
96 
97  void setPreprocessor(std::shared_ptr<Preprocessor> PP) override {
98  this->PP = std::move(PP);
99  }
100 
101  bool
102  handleDeclOccurence(const Decl *D, index::SymbolRoleSet Roles,
103  ArrayRef<index::SymbolRelation> Relations,
104  SourceLocation Loc,
105  index::IndexDataConsumer::ASTNodeInfo ASTNode) override;
106 
107  bool handleMacroOccurence(const IdentifierInfo *Name, const MacroInfo *MI,
108  index::SymbolRoleSet Roles,
109  SourceLocation Loc) override;
110 
111  SymbolSlab takeSymbols() { return std::move(Symbols).build(); }
112  RefSlab takeRefs() { return std::move(Refs).build(); }
113  RelationSlab takeRelations() { return std::move(Relations).build(); }
114 
115  /// Returns true if we are interested in references and declarations from \p
116  /// FID. If this function return false, bodies of functions inside those files
117  /// will be skipped to decrease indexing time.
118  bool shouldIndexFile(FileID FID);
119 
120  void finish() override;
121 
122 private:
123  const Symbol *addDeclaration(const NamedDecl &, SymbolID,
124  bool IsMainFileSymbol);
125  void addDefinition(const NamedDecl &, const Symbol &DeclSymbol);
126  void processRelations(const NamedDecl &ND, const SymbolID &ID,
127  ArrayRef<index::SymbolRelation> Relations);
128 
129  llvm::Optional<std::string> getIncludeHeader(llvm::StringRef QName, FileID);
130  bool isSelfContainedHeader(FileID);
131  // Heuristically headers that only want to be included via an umbrella.
132  static bool isDontIncludeMeHeader(llvm::StringRef);
133 
134  // All Symbols collected from the AST.
135  SymbolSlab::Builder Symbols;
136  // File IDs for Symbol.IncludeHeaders.
137  // The final spelling is calculated in finish().
138  llvm::DenseMap<SymbolID, FileID> IncludeFiles;
139  void setIncludeLocation(const Symbol &S, SourceLocation);
140  // Indexed macros, to be erased if they turned out to be include guards.
141  llvm::DenseSet<const IdentifierInfo *> IndexedMacros;
142  // All refs collected from the AST. It includes:
143  // 1) symbols declared in the preamble and referenced from the main file (
144  // which is not a header), or
145  // 2) symbols declared and referenced from the main file (which is a header)
146  RefSlab::Builder Refs;
147  // All relations collected from the AST.
148  RelationSlab::Builder Relations;
149  ASTContext *ASTCtx;
150  std::shared_ptr<Preprocessor> PP;
151  std::shared_ptr<GlobalCodeCompletionAllocator> CompletionAllocator;
152  std::unique_ptr<CodeCompletionTUInfo> CompletionTUInfo;
153  Options Opts;
154  using DeclRef = std::pair<SourceLocation, index::SymbolRoleSet>;
155  // Symbols referenced from the current TU, flushed on finish().
156  llvm::DenseSet<const NamedDecl *> ReferencedDecls;
157  llvm::DenseSet<const IdentifierInfo *> ReferencedMacros;
158  llvm::DenseMap<const NamedDecl *, std::vector<DeclRef>> DeclRefs;
159  // Maps canonical declaration provided by clang to canonical declaration for
160  // an index symbol, if clangd prefers a different declaration than that
161  // provided by clang. For example, friend declaration might be considered
162  // canonical by clang but should not be considered canonical in the index
163  // unless it's a definition.
164  llvm::DenseMap<const Decl *, const Decl *> CanonicalDecls;
165  // Cache whether to index a file or not.
166  llvm::DenseMap<FileID, bool> FilesToIndexCache;
167  llvm::DenseMap<FileID, bool> HeaderIsSelfContainedCache;
168 };
169 
170 } // namespace clangd
171 } // namespace clang
172 
173 #endif
SourceLocation Loc
&#39;#&#39; location in the include directive
bool handleMacroOccurence(const IdentifierInfo *Name, const MacroInfo *MI, index::SymbolRoleSet Roles, SourceLocation Loc) override
An immutable symbol container that stores a set of symbols.
Definition: Symbol.h:177
An efficient structure of storing large set of symbol references in memory.
Definition: Ref.h:69
Collect declarations (symbols) from an AST.
void initialize(ASTContext &Ctx) override
SymbolSlab::Builder is a mutable container that can &#39;freeze&#39; to SymbolSlab.
Definition: Symbol.h:199
Maps a definition location onto an #include file, based on a set of filename rules.
Context Ctx
std::string QName
std::string FallbackDir
When symbol paths cannot be resolved to absolute paths (e.g.
bool handleDeclOccurence(const Decl *D, index::SymbolRoleSet Roles, ArrayRef< index::SymbolRelation > Relations, SourceLocation Loc, index::IndexDataConsumer::ASTNodeInfo ASTNode) override
bool StoreAllDocumentation
If set to true, SymbolCollector will collect doc for all symbols.
static constexpr llvm::StringLiteral Name
const Decl * D
Definition: XRefs.cpp:849
RefKind
Describes the kind of a cross-reference.
Definition: Ref.h:28
bool shouldIndexFile(FileID FID)
Returns true if we are interested in references and declarations from FID.
RelationSlab::Builder is a mutable container that can &#39;freeze&#39; to RelationSlab.
Definition: Relation.h:70
bool CollectMainFileSymbols
Collect symbols local to main-files, such as static functions and symbols inside an anonymous namespa...
std::function< bool(const SourceManager &, FileID)> FileFilter
If this is set, only collect symbols/references from a file if FileFilter(SM, FID) is true...
RefSlab::Builder is a mutable container that can &#39;freeze&#39; to RefSlab.
Definition: Ref.h:93
static bool shouldCollectSymbol(const NamedDecl &ND, const ASTContext &ASTCtx, const Options &Opts, bool IsMainFileSymbol)
Returns true is ND should be collected.
The class presents a C++ symbol, e.g.
Definition: Symbol.h:36
bool RefsInHeaders
If set to true, SymbolCollector will collect all refs (from main file and included headers); otherwis...
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
void setPreprocessor(std::shared_ptr< Preprocessor > PP) override
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.