| 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 |
|
| 30 |
namespace clang { |
| 31 |
class SourceManager; |
| 32 |
class Decl; |
| 33 |
class DynTypedNode; |
| 34 |
|
| 35 |
namespace 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. |
| 40 |
bool 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. |
| 46 |
SourceLocation 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. |
| 50 |
std::string printQualifiedName(const NamedDecl &ND); |
| 51 |
|
| 52 |
/// Returns the first enclosing namespace scope starting from \p DC. |
| 53 |
std::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'. |
| 58 |
std::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)". |
| 64 |
std::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. |
| 70 |
std::string printTemplateSpecializationArgs(const NamedDecl &ND); |
| 71 |
|
| 72 |
/// Print the Objective-C method name, including the full container name, e.g. |
| 73 |
/// `-[MyClass(Category) method:]` |
| 74 |
std::string printObjCMethod(const ObjCMethodDecl &Method); |
| 75 |
|
| 76 |
/// Print the Objective-C container name including categories, e.g. `MyClass`, |
| 77 |
// `MyClass()`, `MyClass(Category)`, and `MyProtocol`. |
| 78 |
std::string printObjCContainer(const ObjCContainerDecl &C); |
| 79 |
|
| 80 |
/// Returns true if this is a NamedDecl with a reserved name. |
| 81 |
bool 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. |
| 84 |
bool hasReservedScope(const DeclContext &); |
| 85 |
|
| 86 |
/// Gets the symbol ID for a declaration. Returned SymbolID might be null. |
| 87 |
SymbolID 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). |
| 96 |
SymbolID 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. |
| 121 |
const 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. |
| 130 |
Symbol::IncludeDirective |
| 131 |
preferredIncludeDirective(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. |
| 137 |
std::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 |
| 144 |
bool 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. |
| 153 |
bool 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 |
| 159 |
NestedNameSpecifierLoc 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 *>. |
| 164 |
QualType 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. |
| 169 |
std::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. |
| 176 |
TemplateTypeParmTypeLoc 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. |
| 180 |
NamedDecl *getOnlyInstantiation(NamedDecl *TemplatedDecl); |
| 181 |
|
| 182 |
/// Return attributes attached directly to a node. |
| 183 |
std::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. |
| 199 |
std::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:: |
| 215 |
std::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). |
| 233 |
bool 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. |
| 239 |
bool 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. |
| 245 |
llvm::SmallVector<const ParmVarDecl *> |
| 246 |
resolveForwardingParameters(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&&...`). |
| 251 |
bool isExpandedFromParameterPack(const ParmVarDecl *D); |
| 252 |
|
| 253 |
} // namespace clangd |
| 254 |
} // namespace clang |
| 255 |
|
| 256 |
#endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_AST_H |