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

source code of clang-tools-extra/clangd/AST.h