clang-tools  16.0.0git
AST.h
Go to the documentation of this file.
1 //===--- AST.h - Utility AST functions -------------------------*- 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 // Various code that examines C++ source code using AST.
10 //
11 //===----------------------------------------------------------------------===//
12 
13 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_AST_H_
14 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_AST_H_
15 
16 #include "index/SymbolID.h"
17 #include "clang/AST/Decl.h"
18 #include "clang/AST/DeclObjC.h"
19 #include "clang/AST/NestedNameSpecifier.h"
20 #include "clang/AST/TypeLoc.h"
21 #include "clang/Basic/SourceLocation.h"
22 #include "clang/Lex/MacroInfo.h"
23 #include "llvm/ADT/StringRef.h"
24 #include <string>
25 #include <vector>
26 
27 namespace clang {
28 class SourceManager;
29 class Decl;
30 class DynTypedNode;
31 
32 namespace clangd {
33 
34 /// Returns true if the declaration is considered implementation detail based on
35 /// heuristics. For example, a declaration whose name is not explicitly spelled
36 /// in code is considered implementation detail.
37 bool isImplementationDetail(const Decl *D);
38 
39 /// Find the source location of the identifier for \p D.
40 /// Transforms macro locations to locations spelled inside files. All code
41 /// that needs locations of declaration names (e.g. the index) should go through
42 /// this function.
43 SourceLocation nameLocation(const clang::Decl &D, const SourceManager &SM);
44 
45 /// Returns the qualified name of ND. The scope doesn't contain unwritten scopes
46 /// like inline namespaces.
47 std::string printQualifiedName(const NamedDecl &ND);
48 
49 /// Returns the first enclosing namespace scope starting from \p DC.
50 std::string printNamespaceScope(const DeclContext &DC);
51 
52 /// Returns the name of the namespace inside the 'using namespace' directive, as
53 /// written in the code. E.g., passing 'using namespace ::std' will result in
54 /// '::std'.
55 std::string printUsingNamespaceName(const ASTContext &Ctx,
56  const UsingDirectiveDecl &D);
57 
58 /// Prints unqualified name of the decl for the purpose of displaying it to the
59 /// user. Anonymous decls return names of the form "(anonymous {kind})", e.g.
60 /// "(anonymous struct)" or "(anonymous namespace)".
61 std::string printName(const ASTContext &Ctx, const NamedDecl &ND);
62 
63 /// Prints template arguments of a decl as written in the source code, including
64 /// enclosing '<' and '>', e.g for a partial specialization like: template
65 /// <typename U> struct Foo<int, U> will return '<int, U>'. Returns an empty
66 /// string if decl is not a template specialization.
67 std::string printTemplateSpecializationArgs(const NamedDecl &ND);
68 
69 /// Print the Objective-C method name, including the full container name, e.g.
70 /// `-[MyClass(Category) method:]`
71 std::string printObjCMethod(const ObjCMethodDecl &Method);
72 
73 /// Print the Objective-C container name including categories, e.g. `MyClass`,
74 // `MyClass()`, `MyClass(Category)`, and `MyProtocol`.
75 std::string printObjCContainer(const ObjCContainerDecl &C);
76 
77 /// Returns true if this is a NamedDecl with a reserved name.
78 bool hasReservedName(const Decl &);
79 /// Returns true if this scope would be written with a reserved name.
80 /// This does not include unwritten scope elements like __1 in std::__1::vector.
81 bool hasReservedScope(const DeclContext &);
82 
83 /// Gets the symbol ID for a declaration. Returned SymbolID might be null.
84 SymbolID getSymbolID(const Decl *D);
85 
86 /// Gets the symbol ID for a macro. Returned SymbolID might be null.
87 /// Currently, this is an encoded USR of the macro, which incorporates macro
88 /// locations (e.g. file name, offset in file).
89 /// FIXME: the USR semantics might not be stable enough as the ID for index
90 /// macro (e.g. a change in definition offset can result in a different USR). We
91 /// could change these semantics in the future by reimplementing this funcure
92 /// (e.g. avoid USR for macros).
93 SymbolID getSymbolID(const llvm::StringRef MacroName, const MacroInfo *MI,
94  const SourceManager &SM);
95 
96 /// Return the corresponding implementation/definition for the given ObjC
97 /// container if it has one, otherwise, return nullptr.
98 ///
99 /// Objective-C classes can have three types of declarations:
100 ///
101 /// - forward declaration: "@class MyClass;"
102 /// - true declaration (interface definition): "@interface MyClass ... @end"
103 /// - true definition (implementation): "@implementation MyClass ... @end"
104 ///
105 /// Objective-C categories are extensions on classes:
106 ///
107 /// - declaration: "@interface MyClass (Ext) ... @end"
108 /// - definition: "@implementation MyClass (Ext) ... @end"
109 ///
110 /// With one special case, a class extension, which is normally used to keep
111 /// some declarations internal to a file without exposing them in a header.
112 ///
113 /// - class extension declaration: "@interface MyClass () ... @end"
114 /// - which really links to class definition: "@implementation MyClass ... @end"
115 ///
116 /// For Objective-C protocols, e.g. "@protocol MyProtocol ... @end" this will
117 /// return nullptr as protocols don't have an implementation.
118 const ObjCImplDecl *getCorrespondingObjCImpl(const ObjCContainerDecl *D);
119 
120 /// Returns a QualType as string. The result doesn't contain unwritten scopes
121 /// like anonymous/inline namespace.
122 std::string printType(const QualType QT, const DeclContext &CurContext,
123  llvm::StringRef Placeholder = "");
124 
125 /// Indicates if \p D is a template instantiation implicitly generated by the
126 /// compiler, e.g.
127 /// template <class T> struct vector {};
128 /// vector<int> v; // 'vector<int>' is an implicit instantiation
129 bool isImplicitTemplateInstantiation(const NamedDecl *D);
130 /// Indicates if \p D is an explicit template specialization, e.g.
131 /// template <class T> struct vector {};
132 /// template <> struct vector<bool> {}; // <-- explicit specialization
133 ///
134 /// Note that explicit instantiations are NOT explicit specializations, albeit
135 /// they look similar.
136 /// template struct vector<bool>; // <-- explicit instantiation, NOT an
137 /// explicit specialization.
138 bool isExplicitTemplateSpecialization(const NamedDecl *D);
139 
140 /// Returns a nested name specifier loc of \p ND if it was present in the
141 /// source, e.g.
142 /// void ns::something::foo() -> returns 'ns::something'
143 /// void foo() -> returns null
144 NestedNameSpecifierLoc getQualifierLoc(const NamedDecl &ND);
145 
146 // Returns a type corresponding to a declaration of that type.
147 // Unlike the method on ASTContext, attempts to preserve the type as-written
148 // (i.e. vector<T*> rather than vector<type-parameter-0-0 *>.
149 QualType declaredType(const TypeDecl *D);
150 
151 /// Retrieves the deduced type at a given location (auto, decltype).
152 /// It will return the underlying type.
153 /// If the type is an undeduced auto, returns the type itself.
154 llvm::Optional<QualType> getDeducedType(ASTContext &, SourceLocation Loc);
155 
156 // Find the abbreviated-function-template `auto` within a type, or returns null.
157 // Similar to getContainedAutoTypeLoc, but these `auto`s are
158 // TemplateTypeParmTypes for implicit TTPs, instead of AutoTypes.
159 // Also we don't look very hard, just stripping const, references, pointers.
160 // FIXME: handle more type patterns.
161 TemplateTypeParmTypeLoc getContainedAutoParamType(TypeLoc TL);
162 
163 // If TemplatedDecl is the generic body of a template, and the template has
164 // exactly one visible instantiation, return the instantiated body.
165 NamedDecl *getOnlyInstantiation(NamedDecl *TemplatedDecl);
166 
167 /// Return attributes attached directly to a node.
168 std::vector<const Attr *> getAttributes(const DynTypedNode &);
169 
170 /// Gets the nested name specifier necessary for spelling \p ND in \p
171 /// DestContext, at \p InsertionPoint. It selects the shortest suffix of \p ND
172 /// such that it is visible in \p DestContext.
173 /// Returns an empty string if no qualification is necessary. For example, if
174 /// you want to qualify clang::clangd::bar::foo in clang::clangd::x, this
175 /// function will return bar. Note that the result might be sub-optimal for
176 /// classes, e.g. when the \p ND is a member of the base class.
177 ///
178 /// This version considers all the using namespace directives before \p
179 /// InsertionPoint. i.e, if you have `using namespace
180 /// clang::clangd::bar`, this function will return an empty string for the
181 /// example above since no qualification is necessary in that case.
182 /// FIXME: Also take using directives and namespace aliases inside function body
183 /// into account.
184 std::string getQualification(ASTContext &Context,
185  const DeclContext *DestContext,
186  SourceLocation InsertionPoint,
187  const NamedDecl *ND);
188 
189 /// This function uses the \p VisibleNamespaces to figure out if a shorter
190 /// qualification is sufficient for \p ND, and ignores any using namespace
191 /// directives. It can be useful if there's no AST for the DestContext, but some
192 /// pseudo-parsing is done. i.e. if \p ND is ns1::ns2::X and \p DestContext is
193 /// ns1::, users can provide `ns2::` as visible to change the result to be
194 /// empty.
195 /// Elements in VisibleNamespaces should be in the form: `ns::`, with trailing
196 /// "::".
197 /// Note that this is just textual and might be incorrect. e.g. when there are
198 /// two namespaces ns1::a and ns2::a, the function will early exit if "a::" is
199 /// present in \p VisibleNamespaces, no matter whether it is from ns1:: or ns2::
200 std::string getQualification(ASTContext &Context,
201  const DeclContext *DestContext,
202  const NamedDecl *ND,
203  llvm::ArrayRef<std::string> VisibleNamespaces);
204 
205 /// Whether we must avoid computing linkage for D during code completion.
206 /// Clang aggressively caches linkage computation, which is stable after the AST
207 /// is built. Unfortunately the AST is incomplete during code completion, so
208 /// linkage may still change.
209 ///
210 /// Example: `auto x = []{^}` at file scope.
211 /// During code completion, the initializer for x hasn't been parsed yet.
212 /// x has type `undeduced auto`, and external linkage.
213 /// If we compute linkage at this point, the external linkage will be cached.
214 ///
215 /// After code completion the initializer is attached, and x has a lambda type.
216 /// This means x has "unique external" linkage. If we computed linkage above,
217 /// the cached value is incorrect. (clang catches this with an assertion).
218 bool hasUnstableLinkage(const Decl *D);
219 
220 /// Checks whether \p D is more than \p MaxDepth away from translation unit
221 /// scope.
222 /// This is useful for limiting traversals to keep operation latencies
223 /// reasonable.
224 bool isDeeplyNested(const Decl *D, unsigned MaxDepth = 10);
225 
226 /// Recursively resolves the parameters of a FunctionDecl that forwards its
227 /// parameters to another function via variadic template parameters. This can
228 /// for example be used to retrieve the constructor parameter ParmVarDecl for a
229 /// make_unique or emplace_back call.
230 llvm::SmallVector<const ParmVarDecl *>
231 resolveForwardingParameters(const FunctionDecl *D, unsigned MaxDepth = 10);
232 
233 /// Checks whether D is instantiated from a function parameter pack
234 /// whose type is a bare type parameter pack (e.g. `Args...`), or a
235 /// reference to one (e.g. `Args&...` or `Args&&...`).
236 bool isExpandedFromParameterPack(const ParmVarDecl *D);
237 
238 } // namespace clangd
239 } // namespace clang
240 
241 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_AST_H_
Loc
SourceLocation Loc
Definition: KernelNameRestrictionCheck.cpp:45
SymbolID.h
clang::clangd::hasUnstableLinkage
bool hasUnstableLinkage(const Decl *D)
Whether we must avoid computing linkage for D during code completion.
Definition: AST.cpp:680
clang::clangd::declaredType
QualType declaredType(const TypeDecl *D)
Definition: AST.cpp:424
clang::clangd::isExpandedFromParameterPack
bool isExpandedFromParameterPack(const ParmVarDecl *D)
Checks whether D is instantiated from a function parameter pack whose type is a bare type parameter p...
Definition: AST.cpp:984
clang::clangd::isImplicitTemplateInstantiation
bool isImplicitTemplateInstantiation(const NamedDecl *D)
Indicates if D is a template instantiation implicitly generated by the compiler, e....
Definition: AST.cpp:160
Ctx
Context Ctx
Definition: TUScheduler.cpp:553
clang::clangd::getQualifierLoc
NestedNameSpecifierLoc getQualifierLoc(const NamedDecl &ND)
Returns a nested name specifier loc of ND if it was present in the source, e.g.
Definition: AST.cpp:205
clang::clangd::printObjCMethod
std::string printObjCMethod(const ObjCMethodDecl &Method)
Print the Objective-C method name, including the full container name, e.g.
Definition: AST.cpp:308
clang::clangd::printNamespaceScope
std::string printNamespaceScope(const DeclContext &DC)
Returns the first enclosing namespace scope starting from DC.
Definition: AST.cpp:295
clang::clangd::nameLocation
SourceLocation nameLocation(const clang::Decl &D, const SourceManager &SM)
Find the source location of the identifier for D.
Definition: AST.cpp:173
clang::clangd::resolveForwardingParameters
SmallVector< const ParmVarDecl * > resolveForwardingParameters(const FunctionDecl *D, unsigned MaxDepth)
Recursively resolves the parameters of a FunctionDecl that forwards its parameters to another functio...
Definition: AST.cpp:927
clang::clangd::getDeducedType
llvm::Optional< QualType > getDeducedType(ASTContext &ASTCtx, SourceLocation Loc)
Retrieves the deduced type at a given location (auto, decltype).
Definition: AST.cpp:567
clang::clangd::printType
std::string printType(const QualType QT, const DeclContext &CurContext, const llvm::StringRef Placeholder)
Returns a QualType as string.
Definition: AST.cpp:380
ns1::ns2::D
@ D
Definition: CategoricalFeature.h:3
clang::clangd::printName
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:225
Decl
const FunctionDecl * Decl
Definition: AvoidBindCheck.cpp:100
clang::clangd::printQualifiedName
std::string printQualifiedName(const NamedDecl &ND)
Returns the qualified name of ND.
Definition: AST.cpp:183
clang::clangd::printTemplateSpecializationArgs
std::string printTemplateSpecializationArgs(const NamedDecl &ND)
Prints template arguments of a decl as written in the source code, including enclosing '<' and '>',...
Definition: AST.cpp:266
clang::clangd::getOnlyInstantiation
NamedDecl * getOnlyInstantiation(NamedDecl *TemplatedDecl)
Definition: AST.cpp:605
clang::clangd::hasReservedScope
bool hasReservedScope(const DeclContext &DC)
Returns true if this scope would be written with a reserved name.
Definition: AST.cpp:413
clang::doc::SymbolID
std::array< uint8_t, 20 > SymbolID
Definition: Representation.h:31
clang::clangd::getContainedAutoParamType
TemplateTypeParmTypeLoc getContainedAutoParamType(TypeLoc TL)
Definition: AST.cpp:578
clang::clangd::getSymbolID
SymbolID getSymbolID(const Decl *D)
Gets the symbol ID for a declaration. Returned SymbolID might be null.
Definition: AST.cpp:349
clang::clangd::getQualification
std::string getQualification(ASTContext &Context, const DeclContext *DestContext, SourceLocation InsertionPoint, const NamedDecl *ND)
Gets the nested name specifier necessary for spelling ND in DestContext, at InsertionPoint.
Definition: AST.cpp:641
clang::clangd::getCorrespondingObjCImpl
const ObjCImplDecl * getCorrespondingObjCImpl(const ObjCContainerDecl *D)
Return the corresponding implementation/definition for the given ObjC container if it has one,...
Definition: AST.cpp:366
clang::clangd::isDeeplyNested
bool isDeeplyNested(const Decl *D, unsigned MaxDepth)
Checks whether D is more than MaxDepth away from translation unit scope.
Definition: AST.cpp:687
C
const Criteria C
Definition: FunctionCognitiveComplexityCheck.cpp:93
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
clang::clangd::isExplicitTemplateSpecialization
bool isExplicitTemplateSpecialization(const NamedDecl *D)
Indicates if D is an explicit template specialization, e.g.
Definition: AST.cpp:164
clang::clangd::hasReservedName
bool hasReservedName(const Decl &D)
Returns true if this is a NamedDecl with a reserved name.
Definition: AST.cpp:406
clang::clangd::isImplementationDetail
bool isImplementationDetail(const Decl *D)
Returns true if the declaration is considered implementation detail based on heuristics.
Definition: AST.cpp:168
clang::clangd::printObjCContainer
std::string printObjCContainer(const ObjCContainerDecl &C)
Print the Objective-C container name including categories, e.g. MyClass,.
Definition: AST.cpp:328
clang::clangd::getAttributes
std::vector< const Attr * > getAttributes(const DynTypedNode &N)
Return attributes attached directly to a node.
Definition: AST.cpp:617
clang::clangd::printUsingNamespaceName
std::string printUsingNamespaceName(const ASTContext &Ctx, const UsingDirectiveDecl &D)
Returns the name of the namespace inside the 'using namespace' directive, as written in the code.
Definition: AST.cpp:213