clang-tools  10.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/NestedNameSpecifier.h"
19 #include "clang/Basic/SourceLocation.h"
20 #include "clang/Lex/MacroInfo.h"
21 #include "llvm/ADT/DenseSet.h"
22 #include "llvm/ADT/StringRef.h"
23 #include <string>
24 #include <vector>
25 
26 namespace clang {
27 class SourceManager;
28 class Decl;
29 
30 namespace clangd {
31 
32 /// Returns true if the declaration is considered implementation detail based on
33 /// heuristics. For example, a declaration whose name is not explicitly spelled
34 /// in code is considered implementation detail.
35 bool isImplementationDetail(const Decl *D);
36 
37 /// Find the source location of the identifier for \p D.
38 /// Transforms macro locations to locations spelled inside files. All code
39 /// that needs locations of declaration names (e.g. the index) should go through
40 /// this function.
41 SourceLocation nameLocation(const clang::Decl &D, const SourceManager &SM);
42 
43 /// Returns the qualified name of ND. The scope doesn't contain unwritten scopes
44 /// like inline namespaces.
45 std::string printQualifiedName(const NamedDecl &ND);
46 
47 /// Returns the first enclosing namespace scope starting from \p DC.
48 std::string printNamespaceScope(const DeclContext &DC);
49 
50 /// Returns the name of the namespace inside the 'using namespace' directive, as
51 /// written in the code. E.g., passing 'using namespace ::std' will result in
52 /// '::std'.
53 std::string printUsingNamespaceName(const ASTContext &Ctx,
54  const UsingDirectiveDecl &D);
55 
56 /// Prints unqualified name of the decl for the purpose of displaying it to the
57 /// user. Anonymous decls return names of the form "(anonymous {kind})", e.g.
58 /// "(anonymous struct)" or "(anonymous namespace)".
59 std::string printName(const ASTContext &Ctx, const NamedDecl &ND);
60 
61 /// Prints template arguments of a decl as written in the source code, including
62 /// enclosing '<' and '>', e.g for a partial specialization like: template
63 /// <typename U> struct Foo<int, U> will return '<int, U>'. Returns an empty
64 /// string if decl is not a template specialization.
65 std::string printTemplateSpecializationArgs(const NamedDecl &ND);
66 
67 /// Gets the symbol ID for a declaration, if possible.
68 llvm::Optional<SymbolID> getSymbolID(const Decl *D);
69 
70 /// Gets the symbol ID for a macro, if possible.
71 /// Currently, this is an encoded USR of the macro, which incorporates macro
72 /// locations (e.g. file name, offset in file).
73 /// FIXME: the USR semantics might not be stable enough as the ID for index
74 /// macro (e.g. a change in definition offset can result in a different USR). We
75 /// could change these semantics in the future by reimplementing this funcure
76 /// (e.g. avoid USR for macros).
77 llvm::Optional<SymbolID> getSymbolID(const llvm::StringRef MacroName,
78  const MacroInfo *MI,
79  const SourceManager &SM);
80 
81 /// Returns a QualType as string. The result doesn't contain unwritten scopes
82 /// like anonymous/inline namespace.
83 std::string printType(const QualType QT, const DeclContext &CurContext);
84 
85 /// Indicates if \p D is a template instantiation implicitly generated by the
86 /// compiler, e.g.
87 /// template <class T> struct vector {};
88 /// vector<int> v; // 'vector<int>' is an implicit instantiation
89 bool isImplicitTemplateInstantiation(const NamedDecl *D);
90 /// Indicates if \p D is an explicit template specialization, e.g.
91 /// template <class T> struct vector {};
92 /// template <> struct vector<bool> {}; // <-- explicit specialization
93 ///
94 /// Note that explicit instantiations are NOT explicit specializations, albeit
95 /// they look similar.
96 /// template struct vector<bool>; // <-- explicit instantiation, NOT an
97 /// explicit specialization.
98 bool isExplicitTemplateSpecialization(const NamedDecl *D);
99 
100 /// Returns a nested name specifier loc of \p ND if it was present in the
101 /// source, e.g.
102 /// void ns::something::foo() -> returns 'ns::something'
103 /// void foo() -> returns null
104 NestedNameSpecifierLoc getQualifierLoc(const NamedDecl &ND);
105 
106 // Returns a type corresponding to a declaration of that type.
107 // Unlike the method on ASTContext, attempts to preserve the type as-written
108 // (i.e. vector<T*> rather than vector<type-parameter-0-0 *>.
109 QualType declaredType(const TypeDecl *D);
110 
111 /// Retrieves the deduced type at a given location (auto, decltype).
112 /// Retuns None unless Loc starts an auto/decltype token.
113 /// It will return the underlying type.
114 llvm::Optional<QualType> getDeducedType(ASTContext &, SourceLocation Loc);
115 
116 /// Gets the nested name specifier necessary for spelling \p ND in \p
117 /// DestContext, at \p InsertionPoint. It selects the shortest suffix of \p ND
118 /// such that it is visible in \p DestContext.
119 /// Returns an empty string if no qualification is necessary. For example, if
120 /// you want to qualify clang::clangd::bar::foo in clang::clangd::x, this
121 /// function will return bar. Note that the result might be sub-optimal for
122 /// classes, e.g. when the \p ND is a member of the base class.
123 ///
124 /// This version considers all the using namespace directives before \p
125 /// InsertionPoint. i.e, if you have `using namespace
126 /// clang::clangd::bar`, this function will return an empty string for the
127 /// example above since no qualification is necessary in that case.
128 /// FIXME: Also take using directives and namespace aliases inside function body
129 /// into account.
130 std::string getQualification(ASTContext &Context,
131  const DeclContext *DestContext,
132  SourceLocation InsertionPoint,
133  const NamedDecl *ND);
134 
135 /// This function uses the \p VisibleNamespaces to figure out if a shorter
136 /// qualification is sufficient for \p ND, and ignores any using namespace
137 /// directives. It can be useful if there's no AST for the DestContext, but some
138 /// pseudo-parsing is done. i.e. if \p ND is ns1::ns2::X and \p DestContext is
139 /// ns1::, users can provide `ns2::` as visible to change the result to be
140 /// empty.
141 /// Elements in VisibleNamespaces should be in the form: `ns::`, with trailing
142 /// "::".
143 /// Note that this is just textual and might be incorrect. e.g. when there are
144 /// two namespaces ns1::a and ns2::a, the function will early exit if "a::" is
145 /// present in \p VisibleNamespaces, no matter whether it is from ns1:: or ns2::
146 std::string getQualification(ASTContext &Context,
147  const DeclContext *DestContext,
148  const NamedDecl *ND,
149  llvm::ArrayRef<std::string> VisibleNamespaces);
150 
151 } // namespace clangd
152 } // namespace clang
153 
154 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_AST_H_
SourceLocation Loc
&#39;#&#39; location in the include directive
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:208
const FunctionDecl * Decl
std::string printQualifiedName(const NamedDecl &ND)
Returns the qualified name of ND.
Definition: AST.cpp:169
SourceLocation nameLocation(const clang::Decl &D, const SourceManager &SM)
Find the source location of the identifier for D.
Definition: AST.cpp:162
llvm::Optional< QualType > getDeducedType(ASTContext &ASTCtx, SourceLocation Loc)
Retrieves the deduced type at a given location (auto, decltype).
Definition: AST.cpp:418
llvm::Optional< SymbolID > getSymbolID(const Decl *D)
Gets the symbol ID for a declaration, if possible.
Definition: AST.cpp:286
std::string printUsingNamespaceName(const ASTContext &Ctx, const UsingDirectiveDecl &D)
Returns the name of the namespace inside the &#39;using namespace&#39; directive, as written in the code...
Definition: AST.cpp:196
std::string printNamespaceScope(const DeclContext &DC)
Returns the first enclosing namespace scope starting from DC.
Definition: AST.cpp:278
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:188
std::string printTemplateSpecializationArgs(const NamedDecl &ND)
Prints template arguments of a decl as written in the source code, including enclosing &#39;<&#39; and &#39;>&#39;...
Definition: AST.cpp:249
std::string printType(const QualType QT, const DeclContext &CurContext)
Returns a QualType as string.
Definition: AST.cpp:305
Context Ctx
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:437
QualType declaredType(const TypeDecl *D)
Definition: AST.cpp:321
bool isImplicitTemplateInstantiation(const NamedDecl *D)
Indicates if D is a template instantiation implicitly generated by the compiler, e.g.
Definition: AST.cpp:149
SourceLocation InsertionPoint
bool isExplicitTemplateSpecialization(const NamedDecl *D)
Indicates if D is an explicit template specialization, e.g.
Definition: AST.cpp:153
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
bool isImplementationDetail(const Decl *D)
Returns true if the declaration is considered implementation detail based on heuristics.
Definition: AST.cpp:157