clang-tools  16.0.0git
XRefs.h
Go to the documentation of this file.
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/Optional.h"
23 #include "llvm/ADT/StringRef.h"
24 #include "llvm/Support/raw_ostream.h"
25 #include <vector>
26 
27 namespace clang {
28 namespace syntax {
29 class Token;
30 class TokenBuffer;
31 } // namespace syntax
32 namespace clangd {
33 class 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.
41 struct LocatedSymbol {
42  // The (unqualified) name of the symbol.
43  std::string Name;
44  // The canonical or best declaration: where most users find its interface.
46  // Where the symbol is defined, if known. May equal PreferredDeclaration.
47  llvm::Optional<Location> Definition;
48  // SymbolID of the located symbol if available.
50 };
51 llvm::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.
54 std::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).
63 std::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).
72 const syntax::Token *findNearbyIdentifier(const SpelledWord &Word,
73  const syntax::TokenBuffer &TB);
74 
75 /// Get all document links
76 std::vector<DocumentLink> getDocumentLinks(ParsedAST &AST);
77 
78 /// Returns highlights for all usages of a symbol at \p Pos.
79 std::vector<DocumentHighlight> findDocumentHighlights(ParsedAST &AST,
80  Position Pos);
81 
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 {
92  unsigned Attributes = 0;
93  };
94  std::vector<Reference> References;
95  bool HasMore = false;
96 };
97 llvm::raw_ostream &operator<<(llvm::raw_ostream &,
99 
100 /// Returns implementations at a specified \p Pos:
101 /// - overrides for a virtual method;
102 /// - subclasses for a base class;
103 std::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.
110 std::vector<LocatedSymbol> findType(ParsedAST &AST, Position Pos);
111 
112 /// Returns references of the symbol at a specified \p Pos.
113 /// \p Limit limits the number of results returned (0 means no limit).
115  const SymbolIndex *Index = nullptr);
116 
117 /// Get info about symbols at \p Pos.
118 std::vector<SymbolDetails> getSymbolInfo(ParsedAST &AST, Position Pos);
119 
120 /// Find the record types referenced at \p Pos.
121 std::vector<const CXXRecordDecl *> findRecordTypeAt(ParsedAST &AST,
122  Position Pos);
123 
124 /// Given a record type declaration, find its base (parent) types.
125 std::vector<const CXXRecordDecl *> typeParents(const CXXRecordDecl *CXXRD);
126 
127 /// Get type hierarchy information at \p Pos.
128 std::vector<TypeHierarchyItem> getTypeHierarchy(
129  ParsedAST &AST, Position Pos, int Resolve, TypeHierarchyDirection Direction,
130  const SymbolIndex *Index = nullptr, PathRef TUPath = PathRef{});
131 
132 /// Returns direct parents of a TypeHierarchyItem using SymbolIDs stored inside
133 /// the item.
134 llvm::Optional<std::vector<TypeHierarchyItem>>
135 superTypes(const TypeHierarchyItem &Item, const SymbolIndex *Index);
136 /// Returns direct children of a TypeHierarchyItem.
137 std::vector<TypeHierarchyItem> subTypes(const TypeHierarchyItem &Item,
138  const SymbolIndex *Index);
139 
140 void resolveTypeHierarchy(TypeHierarchyItem &Item, int ResolveLevels,
141  TypeHierarchyDirection Direction,
142  const SymbolIndex *Index);
143 
144 /// Get call hierarchy information at \p Pos.
145 std::vector<CallHierarchyItem>
146 prepareCallHierarchy(ParsedAST &AST, Position Pos, PathRef TUPath);
147 
148 std::vector<CallHierarchyIncomingCall>
149 incomingCalls(const CallHierarchyItem &Item, const SymbolIndex *Index);
150 
151 /// Returns all decls that are referenced in the \p FD except local symbols.
152 llvm::DenseSet<const Decl *> getNonLocalDeclRefs(ParsedAST &AST,
153  const FunctionDecl *FD);
154 } // namespace clangd
155 } // namespace clang
156 
157 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_XREFS_H
clang::clangd::incomingCalls
std::vector< CallHierarchyIncomingCall > incomingCalls(const CallHierarchyItem &Item, const SymbolIndex *Index)
Definition: XRefs.cpp:2132
SymbolID.h
clang::clangd::ReferencesResult::References
std::vector< Reference > References
Definition: XRefs.h:94
clang::clangd::findReferences
ReferencesResult findReferences(ParsedAST &AST, Position Pos, uint32_t Limit, const SymbolIndex *Index)
Returns references of the symbol at a specified Pos.
Definition: XRefs.cpp:1305
clang::clangd::SpelledWord
Definition: SourceCode.h:233
clang::clangd::ReferencesResult::HasMore
bool HasMore
Definition: XRefs.h:95
clang::clangd::ReferencesResult::Reference::Loc
Location Loc
Definition: XRefs.h:91
clang::clangd::resolveTypeHierarchy
void resolveTypeHierarchy(TypeHierarchyItem &Item, int ResolveLevels, TypeHierarchyDirection Direction, const SymbolIndex *Index)
Definition: XRefs.cpp:2095
Path.h
clang::clangd::Location
Definition: Protocol.h:211
clang::clangd::ReferencesResult::Declaration
@ Declaration
Definition: XRefs.h:85
clang::clangd::findImplementations
std::vector< LocatedSymbol > findImplementations(ParsedAST &AST, Position Pos, const SymbolIndex *Index)
Returns implementations at a specified Pos:
Definition: XRefs.cpp:1258
Index.h
clang::clangd::typeParents
std::vector< const CXXRecordDecl * > typeParents(const CXXRecordDecl *CXXRD)
Given a record type declaration, find its base (parent) types.
Definition: XRefs.cpp:1979
clang::clangd::ReferencesResult::Override
@ Override
Definition: XRefs.h:88
Pos
size_t Pos
Definition: NoLintDirectiveHandler.cpp:97
Protocol.h
clang::clangd::findType
std::vector< LocatedSymbol > findType(ParsedAST &AST, Position Pos)
Returns symbols for types referenced at Pos.
Definition: XRefs.cpp:1948
clang::clangd::findNearbyIdentifier
const syntax::Token * findNearbyIdentifier(const SpelledWord &Word, const syntax::TokenBuffer &TB)
Definition: XRefs.cpp:656
clang::clangd::superTypes
llvm::Optional< std::vector< TypeHierarchyItem > > superTypes(const TypeHierarchyItem &Item, const SymbolIndex *Index)
Returns direct parents of a TypeHierarchyItem using SymbolIDs stored inside the item.
Definition: XRefs.cpp:2065
clang::clangd::Position
Definition: Protocol.h:156
clang::clangd::locateSymbolAt
std::vector< LocatedSymbol > locateSymbolAt(ParsedAST &AST, Position Pos, const SymbolIndex *Index)
Get definition of symbol at a specified Pos.
Definition: XRefs.cpp:747
clang::clangd::getNonLocalDeclRefs
llvm::DenseSet< const Decl * > getNonLocalDeclRefs(ParsedAST &AST, const FunctionDecl *FD)
Returns all decls that are referenced in the FD except local symbols.
Definition: XRefs.cpp:2189
clang::clangd::getSymbolInfo
std::vector< SymbolDetails > getSymbolInfo(ParsedAST &AST, Position Pos)
Get info about symbols at Pos.
Definition: XRefs.cpp:1480
clang::clangd::ReferencesResult
Definition: XRefs.h:82
clang::clangd::operator<<
llvm::raw_ostream & operator<<(llvm::raw_ostream &OS, const CodeCompletion &C)
Definition: CodeComplete.cpp:2217
clang::clangd::locateSymbolTextually
std::vector< LocatedSymbol > locateSymbolTextually(const SpelledWord &Word, ParsedAST &AST, const SymbolIndex *Index, llvm::StringRef MainFilePath, ASTNodeKind NodeKind)
Definition: XRefs.cpp:546
Word
std::string Word
Definition: FuzzyMatchTests.cpp:39
SourceCode.h
Index
const SymbolIndex * Index
Definition: Dexp.cpp:98
clang::clangd::SymbolIndex
Interface for symbol indexes that can be used for searching or matching symbols among a set of symbol...
Definition: Index.h:113
clang::clangd::TypeHierarchyDirection
TypeHierarchyDirection
Definition: Protocol.h:1384
clang::clangd::ReferencesResult::Reference::Attributes
unsigned Attributes
Definition: XRefs.h:92
clang::clangd::PathRef
llvm::StringRef PathRef
A typedef to represent a ref to file path.
Definition: Path.h:29
clang::clangd::LocatedSymbol::Name
std::string Name
Definition: XRefs.h:43
clang::clangd::getTypeHierarchy
std::vector< TypeHierarchyItem > getTypeHierarchy(ParsedAST &AST, Position Pos, int ResolveLevels, TypeHierarchyDirection Direction, const SymbolIndex *Index, PathRef TUPath)
Get type hierarchy information at Pos.
Definition: XRefs.cpp:2021
clang::clangd::ReferencesResult::Reference
Definition: XRefs.h:90
clang::clangd::LocatedSymbol
Definition: XRefs.h:41
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
clang::clangd::ReferencesResult::Definition
@ Definition
Definition: XRefs.h:86
clang::clangd::LocatedSymbol::ID
SymbolID ID
Definition: XRefs.h:49
clang::clangd::ReferencesResult::ReferenceAttributes
ReferenceAttributes
Definition: XRefs.h:84
clang::clangd::LocatedSymbol::PreferredDeclaration
Location PreferredDeclaration
Definition: XRefs.h:45
clang::clangd::ParsedAST
Stores and provides access to parsed AST.
Definition: ParsedAST.h:46
clang::clangd::SymbolID
Definition: SymbolID.h:32
clang::clangd::getDocumentLinks
std::vector< DocumentLink > getDocumentLinks(ParsedAST &AST)
Get all document links.
Definition: XRefs.cpp:826
clang::clangd::findRecordTypeAt
std::vector< const CXXRecordDecl * > findRecordTypeAt(ParsedAST &AST, Position Pos)
Find the record types referenced at Pos.
Definition: XRefs.cpp:1723
clang::clangd::prepareCallHierarchy
std::vector< CallHierarchyItem > prepareCallHierarchy(ParsedAST &AST, Position Pos, PathRef TUPath)
Get call hierarchy information at Pos.
Definition: XRefs.cpp:2110
clang::clangd::LocatedSymbol::Definition
llvm::Optional< Location > Definition
Definition: XRefs.h:47
clang::clangd::subTypes
std::vector< TypeHierarchyItem > subTypes(const TypeHierarchyItem &Item, const SymbolIndex *Index)
Returns direct children of a TypeHierarchyItem.
Definition: XRefs.cpp:2086
clang::clangd::findDocumentHighlights
std::vector< DocumentHighlight > findDocumentHighlights(ParsedAST &AST, Position Pos)
Returns highlights for all usages of a symbol at Pos.
Definition: XRefs.cpp:1217