clang-tools  14.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/Basic/SourceLocation.h"
21 #include "clang/Lex/MacroInfo.h"
22 #include "llvm/ADT/DenseSet.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 /// Gets the symbol ID for a declaration. Returned SymbolID might be null.
78 SymbolID getSymbolID(const Decl *D);
79 
80 /// Gets the symbol ID for a macro. Returned SymbolID might be null.
81 /// Currently, this is an encoded USR of the macro, which incorporates macro
82 /// locations (e.g. file name, offset in file).
83 /// FIXME: the USR semantics might not be stable enough as the ID for index
84 /// macro (e.g. a change in definition offset can result in a different USR). We
85 /// could change these semantics in the future by reimplementing this funcure
86 /// (e.g. avoid USR for macros).
87 SymbolID getSymbolID(const llvm::StringRef MacroName, const MacroInfo *MI,
88  const SourceManager &SM);
89 
90 /// Returns a QualType as string. The result doesn't contain unwritten scopes
91 /// like anonymous/inline namespace.
92 std::string printType(const QualType QT, const DeclContext &CurContext);
93 
94 /// Indicates if \p D is a template instantiation implicitly generated by the
95 /// compiler, e.g.
96 /// template <class T> struct vector {};
97 /// vector<int> v; // 'vector<int>' is an implicit instantiation
98 bool isImplicitTemplateInstantiation(const NamedDecl *D);
99 /// Indicates if \p D is an explicit template specialization, e.g.
100 /// template <class T> struct vector {};
101 /// template <> struct vector<bool> {}; // <-- explicit specialization
102 ///
103 /// Note that explicit instantiations are NOT explicit specializations, albeit
104 /// they look similar.
105 /// template struct vector<bool>; // <-- explicit instantiation, NOT an
106 /// explicit specialization.
107 bool isExplicitTemplateSpecialization(const NamedDecl *D);
108 
109 /// Returns a nested name specifier loc of \p ND if it was present in the
110 /// source, e.g.
111 /// void ns::something::foo() -> returns 'ns::something'
112 /// void foo() -> returns null
113 NestedNameSpecifierLoc getQualifierLoc(const NamedDecl &ND);
114 
115 // Returns a type corresponding to a declaration of that type.
116 // Unlike the method on ASTContext, attempts to preserve the type as-written
117 // (i.e. vector<T*> rather than vector<type-parameter-0-0 *>.
118 QualType declaredType(const TypeDecl *D);
119 
120 /// Retrieves the deduced type at a given location (auto, decltype).
121 /// It will return the underlying type.
122 /// If the type is an undeduced auto, returns the type itself.
123 llvm::Optional<QualType> getDeducedType(ASTContext &, SourceLocation Loc);
124 
125 /// Return attributes attached directly to a node.
126 std::vector<const Attr *> getAttributes(const DynTypedNode &);
127 
128 /// Gets the nested name specifier necessary for spelling \p ND in \p
129 /// DestContext, at \p InsertionPoint. It selects the shortest suffix of \p ND
130 /// such that it is visible in \p DestContext.
131 /// Returns an empty string if no qualification is necessary. For example, if
132 /// you want to qualify clang::clangd::bar::foo in clang::clangd::x, this
133 /// function will return bar. Note that the result might be sub-optimal for
134 /// classes, e.g. when the \p ND is a member of the base class.
135 ///
136 /// This version considers all the using namespace directives before \p
137 /// InsertionPoint. i.e, if you have `using namespace
138 /// clang::clangd::bar`, this function will return an empty string for the
139 /// example above since no qualification is necessary in that case.
140 /// FIXME: Also take using directives and namespace aliases inside function body
141 /// into account.
142 std::string getQualification(ASTContext &Context,
143  const DeclContext *DestContext,
144  SourceLocation InsertionPoint,
145  const NamedDecl *ND);
146 
147 /// This function uses the \p VisibleNamespaces to figure out if a shorter
148 /// qualification is sufficient for \p ND, and ignores any using namespace
149 /// directives. It can be useful if there's no AST for the DestContext, but some
150 /// pseudo-parsing is done. i.e. if \p ND is ns1::ns2::X and \p DestContext is
151 /// ns1::, users can provide `ns2::` as visible to change the result to be
152 /// empty.
153 /// Elements in VisibleNamespaces should be in the form: `ns::`, with trailing
154 /// "::".
155 /// Note that this is just textual and might be incorrect. e.g. when there are
156 /// two namespaces ns1::a and ns2::a, the function will early exit if "a::" is
157 /// present in \p VisibleNamespaces, no matter whether it is from ns1:: or ns2::
158 std::string getQualification(ASTContext &Context,
159  const DeclContext *DestContext,
160  const NamedDecl *ND,
161  llvm::ArrayRef<std::string> VisibleNamespaces);
162 
163 /// Whether we must avoid computing linkage for D during code completion.
164 /// Clang aggressively caches linkage computation, which is stable after the AST
165 /// is built. Unfortunately the AST is incomplete during code completion, so
166 /// linkage may still change.
167 ///
168 /// Example: `auto x = []{^}` at file scope.
169 /// During code completion, the initializer for x hasn't been parsed yet.
170 /// x has type `undeduced auto`, and external linkage.
171 /// If we compute linkage at this point, the external linkage will be cached.
172 ///
173 /// After code completion the initializer is attached, and x has a lambda type.
174 /// This means x has "unique external" linkage. If we computed linkage above,
175 /// the cached value is incorrect. (clang catches this with an assertion).
176 bool hasUnstableLinkage(const Decl *D);
177 
178 /// Checks whether \p D is more than \p MaxDepth away from translation unit
179 /// scope.
180 /// This is useful for limiting traversals to keep operation latencies
181 /// reasonable.
182 bool isDeeplyNested(const Decl *D, unsigned MaxDepth = 10);
183 
184 } // namespace clangd
185 } // namespace clang
186 
187 #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:549
clang::clangd::declaredType
QualType declaredType(const TypeDecl *D)
Definition: AST.cpp:379
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
InsertionPoint
SourceLocation InsertionPoint
Definition: ExtractFunction.cpp:350
Ctx
Context Ctx
Definition: TUScheduler.cpp:454
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:475
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::doc::SymbolID
std::array< uint8_t, 20 > SymbolID
Definition: Representation.h:30
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:510
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:556
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::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:486
clang::clangd::printType
std::string printType(const QualType QT, const DeclContext &CurContext)
Returns a QualType as string.
Definition: AST.cpp:354
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