clang-tools  9.0.0
FindSymbols.cpp
Go to the documentation of this file.
1 //===--- FindSymbols.cpp ------------------------------------*- 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 #include "FindSymbols.h"
9 
10 #include "AST.h"
11 #include "ClangdUnit.h"
12 #include "FuzzyMatch.h"
13 #include "Logger.h"
14 #include "Quality.h"
15 #include "SourceCode.h"
16 #include "index/Index.h"
17 #include "clang/AST/DeclTemplate.h"
18 #include "clang/Index/IndexDataConsumer.h"
19 #include "clang/Index/IndexSymbol.h"
20 #include "clang/Index/IndexingAction.h"
21 #include "llvm/Support/FormatVariadic.h"
22 #include "llvm/Support/Path.h"
23 #include "llvm/Support/ScopedPrinter.h"
24 
25 #define DEBUG_TYPE "FindSymbols"
26 
27 namespace clang {
28 namespace clangd {
29 
30 namespace {
31 using ScoredSymbolInfo = std::pair<float, SymbolInformation>;
32 struct ScoredSymbolGreater {
33  bool operator()(const ScoredSymbolInfo &L, const ScoredSymbolInfo &R) {
34  if (L.first != R.first)
35  return L.first > R.first;
36  return L.second.name < R.second.name; // Earlier name is better.
37  }
38 };
39 
40 } // namespace
41 
42 llvm::Expected<Location> symbolToLocation(const Symbol &Sym,
43  llvm::StringRef HintPath) {
44  // Prefer the definition over e.g. a function declaration in a header
45  auto &CD = Sym.Definition ? Sym.Definition : Sym.CanonicalDeclaration;
46  auto Uri = URI::parse(CD.FileURI);
47  if (!Uri) {
48  return llvm::make_error<llvm::StringError>(
49  formatv("Could not parse URI '{0}' for symbol '{1}'.", CD.FileURI,
50  Sym.Name),
51  llvm::inconvertibleErrorCode());
52  }
53  auto Path = URI::resolve(*Uri, HintPath);
54  if (!Path) {
55  return llvm::make_error<llvm::StringError>(
56  formatv("Could not resolve path for URI '{0}' for symbol '{1}'.",
57  Uri->toString(), Sym.Name),
58  llvm::inconvertibleErrorCode());
59  }
60  Location L;
61  // Use HintPath as TUPath since there is no TU associated with this
62  // request.
63  L.uri = URIForFile::canonicalize(*Path, HintPath);
64  Position Start, End;
65  Start.line = CD.Start.line();
66  Start.character = CD.Start.column();
67  End.line = CD.End.line();
68  End.character = CD.End.column();
69  L.range = {Start, End};
70  return L;
71 }
72 
73 llvm::Expected<std::vector<SymbolInformation>>
74 getWorkspaceSymbols(llvm::StringRef Query, int Limit,
75  const SymbolIndex *const Index, llvm::StringRef HintPath) {
76  std::vector<SymbolInformation> Result;
77  if (Query.empty() || !Index)
78  return Result;
79 
80  auto Names = splitQualifiedName(Query);
81 
82  FuzzyFindRequest Req;
83  Req.Query = Names.second;
84 
85  // FuzzyFind doesn't want leading :: qualifier
86  bool IsGlobalQuery = Names.first.consume_front("::");
87  // Restrict results to the scope in the query string if present (global or
88  // not).
89  if (IsGlobalQuery || !Names.first.empty())
90  Req.Scopes = {Names.first};
91  else
92  Req.AnyScope = true;
93  if (Limit)
94  Req.Limit = Limit;
95  TopN<ScoredSymbolInfo, ScoredSymbolGreater> Top(
96  Req.Limit ? *Req.Limit : std::numeric_limits<size_t>::max());
97  FuzzyMatcher Filter(Req.Query);
98  Index->fuzzyFind(Req, [HintPath, &Top, &Filter](const Symbol &Sym) {
99  auto Loc = symbolToLocation(Sym, HintPath);
100  if (!Loc) {
101  log("Workspace symbols: {0}", Loc.takeError());
102  return;
103  }
104 
105  SymbolKind SK = indexSymbolKindToSymbolKind(Sym.SymInfo.Kind);
106  std::string Scope = Sym.Scope;
107  llvm::StringRef ScopeRef = Scope;
108  ScopeRef.consume_back("::");
109  SymbolInformation Info = {(Sym.Name + Sym.TemplateSpecializationArgs).str(),
110  SK, *Loc, ScopeRef};
111 
112  SymbolQualitySignals Quality;
113  Quality.merge(Sym);
114  SymbolRelevanceSignals Relevance;
115  Relevance.Name = Sym.Name;
116  Relevance.Query = SymbolRelevanceSignals::Generic;
117  if (auto NameMatch = Filter.match(Sym.Name))
118  Relevance.NameMatch = *NameMatch;
119  else {
120  log("Workspace symbol: {0} didn't match query {1}", Sym.Name,
121  Filter.pattern());
122  return;
123  }
124  Relevance.merge(Sym);
125  auto Score =
126  evaluateSymbolAndRelevance(Quality.evaluate(), Relevance.evaluate());
127  dlog("FindSymbols: {0}{1} = {2}\n{3}{4}\n", Sym.Scope, Sym.Name, Score,
128  Quality, Relevance);
129 
130  Top.push({Score, std::move(Info)});
131  });
132  for (auto &R : std::move(Top).items())
133  Result.push_back(std::move(R.second));
134  return Result;
135 }
136 
137 namespace {
138 llvm::Optional<DocumentSymbol> declToSym(ASTContext &Ctx, const NamedDecl &ND) {
139  auto &SM = Ctx.getSourceManager();
140 
141  SourceLocation NameLoc = findNameLoc(&ND);
142  // getFileLoc is a good choice for us, but we also need to make sure
143  // sourceLocToPosition won't switch files, so we call getSpellingLoc on top of
144  // that to make sure it does not switch files.
145  // FIXME: sourceLocToPosition should not switch files!
146  SourceLocation BeginLoc = SM.getSpellingLoc(SM.getFileLoc(ND.getBeginLoc()));
147  SourceLocation EndLoc = SM.getSpellingLoc(SM.getFileLoc(ND.getEndLoc()));
148  if (NameLoc.isInvalid() || BeginLoc.isInvalid() || EndLoc.isInvalid())
149  return llvm::None;
150 
151  if (!SM.isWrittenInMainFile(NameLoc) || !SM.isWrittenInMainFile(BeginLoc) ||
152  !SM.isWrittenInMainFile(EndLoc))
153  return llvm::None;
154 
155  Position NameBegin = sourceLocToPosition(SM, NameLoc);
156  Position NameEnd = sourceLocToPosition(
157  SM, Lexer::getLocForEndOfToken(NameLoc, 0, SM, Ctx.getLangOpts()));
158 
160  // FIXME: this is not classifying constructors, destructors and operators
161  // correctly (they're all "methods").
162  SymbolKind SK = indexSymbolKindToSymbolKind(SymInfo.Kind);
163 
164  DocumentSymbol SI;
165  SI.name = printName(Ctx, ND);
166  SI.kind = SK;
167  SI.deprecated = ND.isDeprecated();
168  SI.range =
169  Range{sourceLocToPosition(SM, BeginLoc), sourceLocToPosition(SM, EndLoc)};
170  SI.selectionRange = Range{NameBegin, NameEnd};
171  if (!SI.range.contains(SI.selectionRange)) {
172  // 'selectionRange' must be contained in 'range', so in cases where clang
173  // reports unrelated ranges we need to reconcile somehow.
174  SI.range = SI.selectionRange;
175  }
176  return SI;
177 }
178 
179 /// A helper class to build an outline for the parse AST. It traverse the AST
180 /// directly instead of using RecursiveASTVisitor (RAV) for three main reasons:
181 /// - there is no way to keep RAV from traversing subtrees we're not
182 /// interested in. E.g. not traversing function locals or implicit template
183 /// instantiations.
184 /// - it's easier to combine results of recursive passes, e.g.
185 /// - visiting decls is actually simple, so we don't hit the complicated
186 /// cases that RAV mostly helps with (types and expressions, etc.)
187 class DocumentOutline {
188 public:
189  DocumentOutline(ParsedAST &AST) : AST(AST) {}
190 
191  /// Builds the document outline for the generated AST.
192  std::vector<DocumentSymbol> build() {
193  std::vector<DocumentSymbol> Results;
194  for (auto &TopLevel : AST.getLocalTopLevelDecls())
195  traverseDecl(TopLevel, Results);
196  return Results;
197  }
198 
199 private:
200  enum class VisitKind { No, OnlyDecl, DeclAndChildren };
201 
202  void traverseDecl(Decl *D, std::vector<DocumentSymbol> &Results) {
203  if (auto *Templ = llvm::dyn_cast<TemplateDecl>(D))
204  D = Templ->getTemplatedDecl();
205  auto *ND = llvm::dyn_cast<NamedDecl>(D);
206  if (!ND)
207  return;
208  VisitKind Visit = shouldVisit(ND);
209  if (Visit == VisitKind::No)
210  return;
211  llvm::Optional<DocumentSymbol> Sym = declToSym(AST.getASTContext(), *ND);
212  if (!Sym)
213  return;
214  if (Visit == VisitKind::DeclAndChildren)
215  traverseChildren(D, Sym->children);
216  Results.push_back(std::move(*Sym));
217  }
218 
219  void traverseChildren(Decl *D, std::vector<DocumentSymbol> &Results) {
220  auto *Scope = llvm::dyn_cast<DeclContext>(D);
221  if (!Scope)
222  return;
223  for (auto *C : Scope->decls())
224  traverseDecl(C, Results);
225  }
226 
227  VisitKind shouldVisit(NamedDecl *D) {
228  if (D->isImplicit())
229  return VisitKind::No;
230 
231  if (auto Func = llvm::dyn_cast<FunctionDecl>(D)) {
232  // Some functions are implicit template instantiations, those should be
233  // ignored.
234  if (auto *Info = Func->getTemplateSpecializationInfo()) {
235  if (!Info->isExplicitInstantiationOrSpecialization())
236  return VisitKind::No;
237  }
238  // Only visit the function itself, do not visit the children (i.e.
239  // function parameters, etc.)
240  return VisitKind::OnlyDecl;
241  }
242  // Handle template instantiations. We have three cases to consider:
243  // - explicit instantiations, e.g. 'template class std::vector<int>;'
244  // Visit the decl itself (it's present in the code), but not the
245  // children.
246  // - implicit instantiations, i.e. not written by the user.
247  // Do not visit at all, they are not present in the code.
248  // - explicit specialization, e.g. 'template <> class vector<bool> {};'
249  // Visit both the decl and its children, both are written in the code.
250  if (auto *TemplSpec = llvm::dyn_cast<ClassTemplateSpecializationDecl>(D)) {
251  if (TemplSpec->isExplicitInstantiationOrSpecialization())
252  return TemplSpec->isExplicitSpecialization()
253  ? VisitKind::DeclAndChildren
254  : VisitKind::OnlyDecl;
255  return VisitKind::No;
256  }
257  if (auto *TemplSpec = llvm::dyn_cast<VarTemplateSpecializationDecl>(D)) {
258  if (TemplSpec->isExplicitInstantiationOrSpecialization())
259  return TemplSpec->isExplicitSpecialization()
260  ? VisitKind::DeclAndChildren
261  : VisitKind::OnlyDecl;
262  return VisitKind::No;
263  }
264  // For all other cases, visit both the children and the decl.
265  return VisitKind::DeclAndChildren;
266  }
267 
268  ParsedAST &AST;
269 };
270 
271 std::vector<DocumentSymbol> collectDocSymbols(ParsedAST &AST) {
272  return DocumentOutline(AST).build();
273 }
274 } // namespace
275 
276 llvm::Expected<std::vector<DocumentSymbol>> getDocumentSymbols(ParsedAST &AST) {
277  return collectDocSymbols(AST);
278 }
279 
280 } // namespace clangd
281 } // namespace clang
SourceLocation Loc
&#39;#&#39; location in the include directive
int Limit
std::string printName(const ASTContext &Ctx, const NamedDecl &ND)
Prints unqualified name of the decl for the purpose of displaying it to the user. ...
Definition: AST.cpp:90
SignatureQualitySignals Quality
llvm::Expected< std::vector< SymbolInformation > > getWorkspaceSymbols(llvm::StringRef Query, int Limit, const SymbolIndex *const Index, llvm::StringRef HintPath)
Searches for the symbols matching Query.
Definition: FindSymbols.cpp:74
Diagnostics must be generated for this snapshot.
Interface for symbol indexes that can be used for searching or matching symbols among a set of symbol...
Definition: Index.h:85
std::pair< StringRef, StringRef > splitQualifiedName(StringRef QName)
Definition: SourceCode.cpp:391
SymbolKind indexSymbolKindToSymbolKind(index::SymbolKind Kind)
Definition: Protocol.cpp:216
SourceLocation findNameLoc(const clang::Decl *D)
Find the identifier source location of the given D.
Definition: AST.cpp:67
URIForFile uri
The text document&#39;s URI.
Definition: Protocol.h:183
std::vector< CodeCompletionResult > Results
Documents should not be synced at all.
std::vector< std::string > Scopes
If this is non-empty, symbols must be in at least one of the scopes (e.g.
Definition: Index.h:36
llvm::Optional< float > Score
SymbolLocation Definition
The location of the symbol&#39;s definition, if one was found.
Definition: Symbol.h:47
Context Ctx
std::vector< SymbolDetails > getSymbolInfo(ParsedAST &AST, Position Pos)
Get info about symbols at Pos.
Definition: XRefs.cpp:992
clang::find_all_symbols::SymbolInfo SymbolInfo
void log(const char *Fmt, Ts &&... Vals)
Definition: Logger.h:62
std::string Path
A typedef to represent a file path.
Definition: Path.h:20
std::string Query
A query string for the fuzzy find.
Definition: Index.h:29
#define dlog(...)
Definition: Logger.h:72
static URIForFile canonicalize(llvm::StringRef AbsPath, llvm::StringRef TUPath)
Canonicalizes AbsPath via URI.
Definition: Protocol.cpp:32
SymbolKind
The SymbolInfo Type.
Definition: SymbolInfo.h:30
SymbolLocation CanonicalDeclaration
The location of the preferred declaration of the symbol.
Definition: Symbol.h:56
const Decl * D
Definition: XRefs.cpp:868
llvm::Expected< Location > symbolToLocation(const Symbol &Sym, llvm::StringRef HintPath)
Helper function for deriving an LSP Location for a Symbol.
Definition: FindSymbols.cpp:42
Position sourceLocToPosition(const SourceManager &SM, SourceLocation Loc)
Turn a SourceLocation into a [line, column] pair.
Definition: SourceCode.cpp:186
An information message.
Stores and provides access to parsed AST.
Definition: ClangdUnit.h:73
float evaluateSymbolAndRelevance(float SymbolQuality, float SymbolRelevance)
Combine symbol quality and relevance into a single score.
Definition: Quality.cpp:464
int line
Line position in a document (zero-based).
Definition: Protocol.h:128
int character
Character offset on a line in a document (zero-based).
Definition: Protocol.h:133
The class presents a C++ symbol, e.g.
Definition: Symbol.h:36
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
llvm::StringRef Name
The unqualified name of the symbol, e.g. "bar" (for ns::bar).
Definition: Symbol.h:42
llvm::Expected< std::vector< DocumentSymbol > > getDocumentSymbols(ParsedAST &AST)
Retrieves the symbols contained in the "main file" section of an AST in the same order that they appe...
CharSourceRange Range
SourceRange for the file name.
llvm::Optional< llvm::Expected< tooling::AtomicChanges > > Result
Definition: Rename.cpp:36
static llvm::Expected< std::string > resolve(const URI &U, llvm::StringRef HintPath="")
Resolves the absolute path of U.
Definition: URI.cpp:222
static llvm::Expected< URI > parse(llvm::StringRef Uri)
Parse a URI string "<scheme>:[//<authority>/]<path>".
Definition: URI.cpp:164
const SymbolIndex * Index
Definition: Dexp.cpp:84