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/SymbolLocation.h"
20 #include "support/Path.h"
21 #include "clang/AST/ASTTypeTraits.h"
22 #include "clang/AST/Type.h"
23 #include "clang/Format/Format.h"
24 #include "clang/Index/IndexSymbol.h"
25 #include "llvm/ADT/Optional.h"
26 #include "llvm/Support/raw_ostream.h"
27 #include <vector>
28 
29 namespace clang {
30 namespace syntax {
31 class Token;
32 class TokenBuffer;
33 } // namespace syntax
34 namespace clangd {
35 class ParsedAST;
36 
37 // Describes where a symbol is declared and defined (as far as clangd knows).
38 // There are three cases:
39 //  - a declaration only, no definition is known (e.g. only header seen)
40 //  - a declaration and a distinct definition (e.g. function declared in header)
41 //  - a declaration and an equal definition (e.g. inline function, or class)
42 // For some types of symbol, e.g. macros, definition == declaration always.
43 struct LocatedSymbol {
44   // The (unqualified) name of the symbol.
45   std::string Name;
46   // The canonical or best declaration: where most users find its interface.
47   Location PreferredDeclaration;
48   // Where the symbol is defined, if known. May equal PreferredDeclaration.
49   llvm::Optional<Location> Definition;
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>
64 locateSymbolTextually(const SpelledWord &Word, ParsedAST &AST,
65                       const SymbolIndex *Index, const std::string &MainFilePath,
66                       ASTNodeKind NodeKind);
67 
68 // Try to find a proximate occurrence of `Word` as an identifier, which can be
69 // used to resolve it.
70 // (This is for internal use by locateSymbolAt, and is exposed for testing).
71 const syntax::Token *findNearbyIdentifier(const SpelledWord &Word,
72                                           const syntax::TokenBuffer &TB);
73 
74 /// Get all document links
75 std::vector<DocumentLink> getDocumentLinks(ParsedAST &AST);
76 
77 /// Returns highlights for all usages of a symbol at \p Pos.
78 std::vector<DocumentHighlight> findDocumentHighlights(ParsedAST &AST,
79                                                       Position Pos);
80 
81 struct ReferencesResult {
82   std::vector<Location> References;
83   bool HasMore = false;
84 };
85 /// Returns references of the symbol at a specified \p Pos.
86 /// \p Limit limits the number of results returned (0 means no limit).
87 ReferencesResult findReferences(ParsedAST &AST, Position Pos, uint32_t Limit,
88                                 const SymbolIndex *Index = nullptr);
89 
90 /// Get info about symbols at \p Pos.
91 std::vector<SymbolDetails> getSymbolInfo(ParsedAST &AST, Position Pos);
92 
93 /// Find the record type references at \p Pos.
94 const CXXRecordDecl *findRecordTypeAt(ParsedAST &AST, Position Pos);
95 
96 /// Given a record type declaration, find its base (parent) types.
97 std::vector<const CXXRecordDecl *> typeParents(const CXXRecordDecl *CXXRD);
98 
99 /// Get type hierarchy information at \p Pos.
100 llvm::Optional<TypeHierarchyItem> getTypeHierarchy(
101     ParsedAST &AST, Position Pos, int Resolve, TypeHierarchyDirection Direction,
102     const SymbolIndex *Index = nullptr, PathRef TUPath = PathRef{});
103 
104 void resolveTypeHierarchy(TypeHierarchyItem &Item, int ResolveLevels,
105                           TypeHierarchyDirection Direction,
106                           const SymbolIndex *Index);
107 
108 /// Returns all decls that are referenced in the \p FD except local symbols.
109 llvm::DenseSet<const Decl *> getNonLocalDeclRefs(ParsedAST &AST,
110                                                  const FunctionDecl *FD);
111 } // namespace clangd
112 } // namespace clang
113 
114 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_XREFS_H
115