clang-tools  9.0.0
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 "ClangdUnit.h"
17 #include "FormattedString.h"
18 #include "Protocol.h"
19 #include "index/Index.h"
20 #include "index/SymbolLocation.h"
21 #include "clang/Index/IndexSymbol.h"
22 #include "llvm/ADT/Optional.h"
23 #include "llvm/Support/raw_ostream.h"
24 #include <vector>
25 
26 namespace clang {
27 namespace clangd {
28 
29 // Describes where a symbol is declared and defined (as far as clangd knows).
30 // There are three cases:
31 // - a declaration only, no definition is known (e.g. only header seen)
32 // - a declaration and a distinct definition (e.g. function declared in header)
33 // - a declaration and an equal definition (e.g. inline function, or class)
34 // For some types of symbol, e.g. macros, definition == declaration always.
35 struct LocatedSymbol {
36  // The (unqualified) name of the symbol.
37  std::string Name;
38  // The canonical or best declaration: where most users find its interface.
40  // Where the symbol is defined, if known. May equal PreferredDeclaration.
41  llvm::Optional<Location> Definition;
42 };
43 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const LocatedSymbol &);
44 /// Get definition of symbol at a specified \p Pos.
45 /// Multiple locations may be returned, corresponding to distinct symbols.
46 std::vector<LocatedSymbol> locateSymbolAt(ParsedAST &AST, Position Pos,
47  const SymbolIndex *Index = nullptr);
48 
49 /// Returns highlights for all usages of a symbol at \p Pos.
50 std::vector<DocumentHighlight> findDocumentHighlights(ParsedAST &AST,
51  Position Pos);
52 
53 /// Contains detailed information about a Symbol. Especially useful when
54 /// generating hover responses. It can be rendered as a hover panel, or
55 /// embedding clients can use the structured information to provide their own
56 /// UI.
57 struct HoverInfo {
58  /// Represents parameters of a function, a template or a macro.
59  /// For example:
60  /// - void foo(ParamType Name = DefaultValue)
61  /// - #define FOO(Name)
62  /// - template <ParamType Name = DefaultType> class Foo {};
63  struct Param {
64  /// The pretty-printed parameter type, e.g. "int", or "typename" (in
65  /// TemplateParameters)
66  llvm::Optional<std::string> Type;
67  /// None for unnamed parameters.
68  llvm::Optional<std::string> Name;
69  /// None if no default is provided.
70  llvm::Optional<std::string> Default;
71  };
72 
73  /// For a variable named Bar, declared in clang::clangd::Foo::getFoo the
74  /// following fields will hold:
75  /// - NamespaceScope: clang::clangd::
76  /// - LocalScope: Foo::getFoo::
77  /// - Name: Bar
78 
79  /// Scopes might be None in cases where they don't make sense, e.g. macros and
80  /// auto/decltype.
81  /// Contains all of the enclosing namespaces, empty string means global
82  /// namespace.
83  llvm::Optional<std::string> NamespaceScope;
84  /// Remaining named contexts in symbol's qualified name, empty string means
85  /// symbol is not local.
86  std::string LocalScope;
87  /// Name of the symbol, does not contain any "::".
88  std::string Name;
89  llvm::Optional<Range> SymRange;
90  /// Scope containing the symbol. e.g, "global namespace", "function x::Y"
91  /// - None for deduced types, e.g "auto", "decltype" keywords.
93  std::string Documentation;
94  /// Source code containing the definition of the symbol.
95  std::string Definition;
96 
97  /// Pretty-printed variable type.
98  /// Set only for variables.
99  llvm::Optional<std::string> Type;
100  /// Set for functions and lambadas.
101  llvm::Optional<std::string> ReturnType;
102  /// Set for functions, lambdas and macros with parameters.
103  llvm::Optional<std::vector<Param>> Parameters;
104  /// Set for all templates(function, class, variable).
105  llvm::Optional<std::vector<Param>> TemplateParameters;
106  /// Contains the evaluated value of the symbol if available.
107  llvm::Optional<std::string> Value;
108 
109  /// Produce a user-readable information.
110  FormattedString present() const;
111 };
112 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const HoverInfo::Param &);
113 inline bool operator==(const HoverInfo::Param &LHS,
114  const HoverInfo::Param &RHS) {
115  return std::tie(LHS.Type, LHS.Name, LHS.Default) ==
116  std::tie(RHS.Type, RHS.Name, RHS.Default);
117 }
118 
119 /// Get the hover information when hovering at \p Pos.
120 llvm::Optional<HoverInfo> getHover(ParsedAST &AST, Position Pos,
121  format::FormatStyle Style,
122  const SymbolIndex *Index);
123 
124 /// Returns reference locations of the symbol at a specified \p Pos.
125 /// \p Limit limits the number of results returned (0 means no limit).
126 std::vector<Location> findReferences(ParsedAST &AST, Position Pos,
127  uint32_t Limit,
128  const SymbolIndex *Index = nullptr);
129 
130 /// Get info about symbols at \p Pos.
131 std::vector<SymbolDetails> getSymbolInfo(ParsedAST &AST, Position Pos);
132 
133 /// Find the record type references at \p Pos.
134 const CXXRecordDecl *findRecordTypeAt(ParsedAST &AST, Position Pos);
135 
136 /// Given a record type declaration, find its base (parent) types.
137 std::vector<const CXXRecordDecl *> typeParents(const CXXRecordDecl *CXXRD);
138 
139 /// Get type hierarchy information at \p Pos.
140 llvm::Optional<TypeHierarchyItem> getTypeHierarchy(
141  ParsedAST &AST, Position Pos, int Resolve, TypeHierarchyDirection Direction,
142  const SymbolIndex *Index = nullptr, PathRef TUPath = PathRef{});
143 
144 void resolveTypeHierarchy(TypeHierarchyItem &Item, int ResolveLevels,
145  TypeHierarchyDirection Direction,
146  const SymbolIndex *Index);
147 
148 /// Retrieves the deduced type at a given location (auto, decltype).
149 /// Retuns None unless SourceLocationBeg starts an auto/decltype token.
150 /// It will return the underlying type.
151 llvm::Optional<QualType> getDeducedType(ParsedAST &AST,
152  SourceLocation SourceLocationBeg);
153 
154 /// Check if there is a deduced type at a given location (auto, decltype).
155 /// SourceLocationBeg must point to the first character of the token
156 bool hasDeducedType(ParsedAST &AST, SourceLocation SourceLocationBeg);
157 
158 } // namespace clangd
159 } // namespace clang
160 
161 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_XREFS_H
llvm::Optional< QualType > getDeducedType(ParsedAST &AST, SourceLocation SourceLocationBeg)
Retrieves the deduced type at a given location (auto, decltype).
Definition: XRefs.cpp:874
int Limit
Contains detailed information about a Symbol.
Definition: XRefs.h:57
void resolveTypeHierarchy(TypeHierarchyItem &Item, int ResolveLevels, TypeHierarchyDirection Direction, const SymbolIndex *Index)
Definition: XRefs.cpp:1255
Interface for symbol indexes that can be used for searching or matching symbols among a set of symbol...
Definition: Index.h:85
llvm::Optional< std::string > Name
None for unnamed parameters.
Definition: XRefs.h:68
llvm::Optional< Location > Definition
Definition: XRefs.h:41
llvm::StringRef PathRef
A typedef to represent a ref to file path.
Definition: Path.h:23
llvm::Optional< std::string > Type
Pretty-printed variable type.
Definition: XRefs.h:99
llvm::Optional< std::vector< Param > > Parameters
Set for functions, lambdas and macros with parameters.
Definition: XRefs.h:103
A structured string representation that could be converted to markdown or plaintext upon requrest...
Represents parameters of a function, a template or a macro.
Definition: XRefs.h:63
std::string Definition
Source code containing the definition of the symbol.
Definition: XRefs.h:95
llvm::Optional< std::string > Type
The pretty-printed parameter type, e.g.
Definition: XRefs.h:66
std::vector< SymbolDetails > getSymbolInfo(ParsedAST &AST, Position Pos)
Get info about symbols at Pos.
Definition: XRefs.cpp:992
std::string Name
Name of the symbol, does not contain any "::".
Definition: XRefs.h:88
llvm::Optional< HoverInfo > getHover(ParsedAST &AST, Position Pos, format::FormatStyle Style, const SymbolIndex *Index)
Get the hover information when hovering at Pos.
Definition: XRefs.cpp:899
bool operator==(const Ref &L, const Ref &R)
Definition: Ref.h:61
llvm::Optional< Range > SymRange
Definition: XRefs.h:89
llvm::Optional< std::string > Default
None if no default is provided.
Definition: XRefs.h:70
Location PreferredDeclaration
Definition: XRefs.h:39
std::vector< DocumentHighlight > findDocumentHighlights(ParsedAST &AST, Position Pos)
Returns highlights for all usages of a symbol at Pos.
Definition: XRefs.cpp:436
std::string LocalScope
Remaining named contexts in symbol&#39;s qualified name, empty string means symbol is not local...
Definition: XRefs.h:86
llvm::Optional< std::string > NamespaceScope
For a variable named Bar, declared in clang::clangd::Foo::getFoo the following fields will hold: ...
Definition: XRefs.h:83
Stores and provides access to parsed AST.
Definition: ClangdUnit.h:73
llvm::Optional< std::vector< Param > > TemplateParameters
Set for all templates(function, class, variable).
Definition: XRefs.h:105
std::vector< Location > findReferences(ParsedAST &AST, Position Pos, uint32_t Limit, const SymbolIndex *Index)
Returns reference locations of the symbol at a specified Pos.
Definition: XRefs.cpp:935
llvm::Optional< std::string > ReturnType
Set for functions and lambadas.
Definition: XRefs.h:101
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
const CXXRecordDecl * findRecordTypeAt(ParsedAST &AST, Position Pos)
Find the record type references at Pos.
Definition: XRefs.cpp:1164
SymbolKind
A symbol kind.
Definition: Protocol.h:299
llvm::Optional< std::string > Value
Contains the evaluated value of the symbol if available.
Definition: XRefs.h:107
llvm::Optional< TypeHierarchyItem > getTypeHierarchy(ParsedAST &AST, Position Pos, int ResolveLevels, TypeHierarchyDirection Direction, const SymbolIndex *Index, PathRef TUPath)
Get type hierarchy information at Pos.
Definition: XRefs.cpp:1221
std::vector< LocatedSymbol > locateSymbolAt(ParsedAST &AST, Position Pos, const SymbolIndex *Index)
Get definition of symbol at a specified Pos.
Definition: XRefs.cpp:261
bool hasDeducedType(ParsedAST &AST, SourceLocation SourceLocationBeg)
Retrieves the deduced type at a given location (auto, decltype).
Definition: XRefs.cpp:895
SymbolKind Kind
Scope containing the symbol.
Definition: XRefs.h:92
llvm::raw_ostream & operator<<(llvm::raw_ostream &OS, const CodeCompletion &C)
std::string Documentation
Definition: XRefs.h:93
std::vector< const CXXRecordDecl * > typeParents(const CXXRecordDecl *CXXRD)
Given a record type declaration, find its base (parent) types.
Definition: XRefs.cpp:1190
const SymbolIndex * Index
Definition: Dexp.cpp:84
static cl::opt< std::string > FormatStyle("format-style", cl::desc(R"( Style for formatting code around applied fixes: - 'none' (default) turns off formatting - 'file' (literally 'file', not a placeholder) uses .clang-format file in the closest parent directory - '{ <json> }' specifies options inline, e.g. -format-style='{BasedOnStyle: llvm, IndentWidth: 8}' - 'llvm', 'google', 'webkit', 'mozilla' See clang-format documentation for the up-to-date information about formatting styles and options. This option overrides the 'FormatStyle` option in .clang-tidy file, if any. )"), cl::init("none"), cl::cat(ClangTidyCategory))