clang-tools  15.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 /// Returns a QualType as string. The result doesn't contain unwritten scopes
97 /// like anonymous/inline namespace.
98 std::string printType(const QualType QT, const DeclContext &CurContext,
99  llvm::StringRef Placeholder = "");
100 
101 /// Indicates if \p D is a template instantiation implicitly generated by the
102 /// compiler, e.g.
103 /// template <class T> struct vector {};
104 /// vector<int> v; // 'vector<int>' is an implicit instantiation
105 bool isImplicitTemplateInstantiation(const NamedDecl *D);
106 /// Indicates if \p D is an explicit template specialization, e.g.
107 /// template <class T> struct vector {};
108 /// template <> struct vector<bool> {}; // <-- explicit specialization
109 ///
110 /// Note that explicit instantiations are NOT explicit specializations, albeit
111 /// they look similar.
112 /// template struct vector<bool>; // <-- explicit instantiation, NOT an
113 /// explicit specialization.
114 bool isExplicitTemplateSpecialization(const NamedDecl *D);
115 
116 /// Returns a nested name specifier loc of \p ND if it was present in the
117 /// source, e.g.
118 /// void ns::something::foo() -> returns 'ns::something'
119 /// void foo() -> returns null
120 NestedNameSpecifierLoc getQualifierLoc(const NamedDecl &ND);
121 
122 // Returns a type corresponding to a declaration of that type.
123 // Unlike the method on ASTContext, attempts to preserve the type as-written
124 // (i.e. vector<T*> rather than vector<type-parameter-0-0 *>.
125 QualType declaredType(const TypeDecl *D);
126 
127 /// Retrieves the deduced type at a given location (auto, decltype).
128 /// It will return the underlying type.
129 /// If the type is an undeduced auto, returns the type itself.
130 llvm::Optional<QualType> getDeducedType(ASTContext &, SourceLocation Loc);
131 
132 // Find the abbreviated-function-template `auto` within a type, or returns null.
133 // Similar to getContainedAutoTypeLoc, but these `auto`s are
134 // TemplateTypeParmTypes for implicit TTPs, instead of AutoTypes.
135 // Also we don't look very hard, just stripping const, references, pointers.
136 // FIXME: handle more type patterns.
137 TemplateTypeParmTypeLoc getContainedAutoParamType(TypeLoc TL);
138 
139 // If TemplatedDecl is the generic body of a template, and the template has
140 // exactly one visible instantiation, return the instantiated body.
141 NamedDecl *getOnlyInstantiation(NamedDecl *TemplatedDecl);
142 
143 /// Return attributes attached directly to a node.
144 std::vector<const Attr *> getAttributes(const DynTypedNode &);
145 
146 /// Gets the nested name specifier necessary for spelling \p ND in \p
147 /// DestContext, at \p InsertionPoint. It selects the shortest suffix of \p ND
148 /// such that it is visible in \p DestContext.
149 /// Returns an empty string if no qualification is necessary. For example, if
150 /// you want to qualify clang::clangd::bar::foo in clang::clangd::x, this
151 /// function will return bar. Note that the result might be sub-optimal for
152 /// classes, e.g. when the \p ND is a member of the base class.
153 ///
154 /// This version considers all the using namespace directives before \p
155 /// InsertionPoint. i.e, if you have `using namespace
156 /// clang::clangd::bar`, this function will return an empty string for the
157 /// example above since no qualification is necessary in that case.
158 /// FIXME: Also take using directives and namespace aliases inside function body
159 /// into account.
160 std::string getQualification(ASTContext &Context,
161  const DeclContext *DestContext,
162  SourceLocation InsertionPoint,
163  const NamedDecl *ND);
164 
165 /// This function uses the \p VisibleNamespaces to figure out if a shorter
166 /// qualification is sufficient for \p ND, and ignores any using namespace
167 /// directives. It can be useful if there's no AST for the DestContext, but some
168 /// pseudo-parsing is done. i.e. if \p ND is ns1::ns2::X and \p DestContext is
169 /// ns1::, users can provide `ns2::` as visible to change the result to be
170 /// empty.
171 /// Elements in VisibleNamespaces should be in the form: `ns::`, with trailing
172 /// "::".
173 /// Note that this is just textual and might be incorrect. e.g. when there are
174 /// two namespaces ns1::a and ns2::a, the function will early exit if "a::" is
175 /// present in \p VisibleNamespaces, no matter whether it is from ns1:: or ns2::
176 std::string getQualification(ASTContext &Context,
177  const DeclContext *DestContext,
178  const NamedDecl *ND,
179  llvm::ArrayRef<std::string> VisibleNamespaces);
180 
181 /// Whether we must avoid computing linkage for D during code completion.
182 /// Clang aggressively caches linkage computation, which is stable after the AST
183 /// is built. Unfortunately the AST is incomplete during code completion, so
184 /// linkage may still change.
185 ///
186 /// Example: `auto x = []{^}` at file scope.
187 /// During code completion, the initializer for x hasn't been parsed yet.
188 /// x has type `undeduced auto`, and external linkage.
189 /// If we compute linkage at this point, the external linkage will be cached.
190 ///
191 /// After code completion the initializer is attached, and x has a lambda type.
192 /// This means x has "unique external" linkage. If we computed linkage above,
193 /// the cached value is incorrect. (clang catches this with an assertion).
194 bool hasUnstableLinkage(const Decl *D);
195 
196 /// Checks whether \p D is more than \p MaxDepth away from translation unit
197 /// scope.
198 /// This is useful for limiting traversals to keep operation latencies
199 /// reasonable.
200 bool isDeeplyNested(const Decl *D, unsigned MaxDepth = 10);
201 
202 } // namespace clangd
203 } // namespace clang
204 
205 #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:654
clang::clangd::declaredType
QualType declaredType(const TypeDecl *D)
Definition: AST.cpp:398
clang::clangd::isImplicitTemplateInstantiation
bool isImplicitTemplateInstantiation(const NamedDecl *D)
Indicates if D is a template instantiation implicitly generated by the compiler, e....
Definition: AST.cpp:154
Ctx
Context Ctx
Definition: TUScheduler.cpp:495
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:193
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:296
clang::clangd::printNamespaceScope
std::string printNamespaceScope(const DeclContext &DC)
Returns the first enclosing namespace scope starting from DC.
Definition: AST.cpp:283
clang::clangd::nameLocation
SourceLocation nameLocation(const clang::Decl &D, const SourceManager &SM)
Find the source location of the identifier for D.
Definition: AST.cpp:167
clang::clangd::getDeducedType
llvm::Optional< QualType > getDeducedType(ASTContext &ASTCtx, SourceLocation Loc)
Retrieves the deduced type at a given location (auto, decltype).
Definition: AST.cpp:541
clang::clangd::printType
std::string printType(const QualType QT, const DeclContext &CurContext, const llvm::StringRef Placeholder)
Returns a QualType as string.
Definition: AST.cpp:354
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:213
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:174
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:254
clang::clangd::getOnlyInstantiation
NamedDecl * getOnlyInstantiation(NamedDecl *TemplatedDecl)
Definition: AST.cpp:579
clang::clangd::hasReservedScope
bool hasReservedScope(const DeclContext &DC)
Returns true if this scope would be written with a reserved name.
Definition: AST.cpp:387
clang::doc::SymbolID
std::array< uint8_t, 20 > SymbolID
Definition: Representation.h:30
clang::clangd::getContainedAutoParamType
TemplateTypeParmTypeLoc getContainedAutoParamType(TypeLoc TL)
Definition: AST.cpp:552
clang::clangd::getSymbolID
SymbolID getSymbolID(const Decl *D)
Gets the symbol ID for a declaration. Returned SymbolID might be null.
Definition: AST.cpp:337
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:615
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:661
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:158
clang::clangd::hasReservedName
bool hasReservedName(const Decl &D)
Returns true if this is a NamedDecl with a reserved name.
Definition: AST.cpp:380
clang::clangd::isImplementationDetail
bool isImplementationDetail(const Decl *D)
Returns true if the declaration is considered implementation detail based on heuristics.
Definition: AST.cpp:162
clang::clangd::printObjCContainer
std::string printObjCContainer(const ObjCContainerDecl &C)
Print the Objective-C container name including categories, e.g. MyClass,.
Definition: AST.cpp:316
clang::clangd::getAttributes
std::vector< const Attr * > getAttributes(const DynTypedNode &N)
Return attributes attached directly to a node.
Definition: AST.cpp:591
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:201