1//===--- XRefs.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//
9// Features that traverse references between symbols.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_XREFS_H
14#define LLVM_CLANG_TOOLS_EXTRA_CLANGD_XREFS_H
15
16#include "Protocol.h"
17#include "SourceCode.h"
18#include "index/Index.h"
19#include "index/SymbolID.h"
20#include "support/Path.h"
21#include "clang/AST/ASTTypeTraits.h"
22#include "llvm/ADT/StringRef.h"
23#include "llvm/Support/raw_ostream.h"
24#include <optional>
25#include <vector>
26
27namespace clang {
28namespace syntax {
29class Token;
30class TokenBuffer;
31} // namespace syntax
32namespace clangd {
33class ParsedAST;
34
35// Describes where a symbol is declared and defined (as far as clangd knows).
36// There are three cases:
37// - a declaration only, no definition is known (e.g. only header seen)
38// - a declaration and a distinct definition (e.g. function declared in header)
39// - a declaration and an equal definition (e.g. inline function, or class)
40// For some types of symbol, e.g. macros, definition == declaration always.
41struct LocatedSymbol {
42 // The (unqualified) name of the symbol.
43 std::string Name;
44 // The canonical or best declaration: where most users find its interface.
45 Location PreferredDeclaration;
46 // Where the symbol is defined, if known. May equal PreferredDeclaration.
47 std::optional<Location> Definition;
48 // SymbolID of the located symbol if available.
49 SymbolID ID;
50};
51llvm::raw_ostream &operator<<(llvm::raw_ostream &, const LocatedSymbol &);
52/// Get definition of symbol at a specified \p Pos.
53/// Multiple locations may be returned, corresponding to distinct symbols.
54std::vector<LocatedSymbol> locateSymbolAt(ParsedAST &AST, Position Pos,
55 const SymbolIndex *Index = nullptr);
56
57// Tries to provide a textual fallback for locating a symbol by looking up the
58// word under the cursor as a symbol name in the index.
59// The aim is to pick up references to symbols in contexts where
60// AST-based resolution does not work, such as comments, strings, and PP
61// disabled regions.
62// (This is for internal use by locateSymbolAt, and is exposed for testing).
63std::vector<LocatedSymbol> locateSymbolTextually(const SpelledWord &Word,
64 ParsedAST &AST,
65 const SymbolIndex *Index,
66 llvm::StringRef MainFilePath,
67 ASTNodeKind NodeKind);
68
69// Try to find a proximate occurrence of `Word` as an identifier, which can be
70// used to resolve it.
71// (This is for internal use by locateSymbolAt, and is exposed for testing).
72const syntax::Token *findNearbyIdentifier(const SpelledWord &Word,
73 const syntax::TokenBuffer &TB);
74
75/// Get all document links
76std::vector<DocumentLink> getDocumentLinks(ParsedAST &AST);
77
78/// Returns highlights for all usages of a symbol at \p Pos.
79std::vector<DocumentHighlight> findDocumentHighlights(ParsedAST &AST,
80 Position Pos);
81
82struct ReferencesResult {
83 // Bitmask describing whether the occurrence is a declaration, definition etc.
84 enum ReferenceAttributes : unsigned {
85 Declaration = 1 << 0,
86 Definition = 1 << 1,
87 // The occurrence is an override of the target base method.
88 Override = 1 << 2,
89 };
90 struct Reference {
91 ReferenceLocation Loc;
92 unsigned Attributes = 0;
93 };
94 std::vector<Reference> References;
95 bool HasMore = false;
96};
97llvm::raw_ostream &operator<<(llvm::raw_ostream &,
98 const ReferencesResult::Reference &);
99
100/// Returns implementations at a specified \p Pos:
101/// - overrides for a virtual method;
102/// - subclasses for a base class;
103std::vector<LocatedSymbol> findImplementations(ParsedAST &AST, Position Pos,
104 const SymbolIndex *Index);
105
106/// Returns symbols for types referenced at \p Pos.
107///
108/// For example, given `b^ar()` wher bar return Foo, this function returns the
109/// definition of class Foo.
110std::vector<LocatedSymbol> findType(ParsedAST &AST, Position Pos,
111 const SymbolIndex *Index);
112
113/// Returns references of the symbol at a specified \p Pos.
114/// \p Limit limits the number of results returned (0 means no limit).
115ReferencesResult findReferences(ParsedAST &AST, Position Pos, uint32_t Limit,
116 const SymbolIndex *Index = nullptr,
117 bool AddContext = false);
118
119/// Get info about symbols at \p Pos.
120std::vector<SymbolDetails> getSymbolInfo(ParsedAST &AST, Position Pos);
121
122/// Find the record types referenced at \p Pos.
123std::vector<const CXXRecordDecl *> findRecordTypeAt(ParsedAST &AST,
124 Position Pos);
125
126/// Given a record type declaration, find its base (parent) types.
127std::vector<const CXXRecordDecl *> typeParents(const CXXRecordDecl *CXXRD);
128
129/// Get type hierarchy information at \p Pos.
130std::vector<TypeHierarchyItem> getTypeHierarchy(
131 ParsedAST &AST, Position Pos, int Resolve, TypeHierarchyDirection Direction,
132 const SymbolIndex *Index = nullptr, PathRef TUPath = PathRef{});
133
134/// Returns direct parents of a TypeHierarchyItem using SymbolIDs stored inside
135/// the item.
136std::optional<std::vector<TypeHierarchyItem>>
137superTypes(const TypeHierarchyItem &Item, const SymbolIndex *Index);
138/// Returns direct children of a TypeHierarchyItem.
139std::vector<TypeHierarchyItem> subTypes(const TypeHierarchyItem &Item,
140 const SymbolIndex *Index);
141
142void resolveTypeHierarchy(TypeHierarchyItem &Item, int ResolveLevels,
143 TypeHierarchyDirection Direction,
144 const SymbolIndex *Index);
145
146/// Get call hierarchy information at \p Pos.
147std::vector<CallHierarchyItem>
148prepareCallHierarchy(ParsedAST &AST, Position Pos, PathRef TUPath);
149
150std::vector<CallHierarchyIncomingCall>
151incomingCalls(const CallHierarchyItem &Item, const SymbolIndex *Index);
152
153std::vector<CallHierarchyOutgoingCall>
154outgoingCalls(const CallHierarchyItem &Item, const SymbolIndex *Index);
155
156/// Returns all decls that are referenced in the \p FD except local symbols.
157llvm::DenseSet<const Decl *> getNonLocalDeclRefs(ParsedAST &AST,
158 const FunctionDecl *FD);
159} // namespace clangd
160} // namespace clang
161
162#endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_XREFS_H
163

source code of clang-tools-extra/clangd/XRefs.h