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 /// It will return the underlying type. 113 llvm::Optional<QualType> getDeducedType(ASTContext &, SourceLocation Loc); 114 115 /// Gets the nested name specifier necessary for spelling \p ND in \p 116 /// DestContext, at \p InsertionPoint. It selects the shortest suffix of \p ND 117 /// such that it is visible in \p DestContext. 118 /// Returns an empty string if no qualification is necessary. For example, if 119 /// you want to qualify clang::clangd::bar::foo in clang::clangd::x, this 120 /// function will return bar. Note that the result might be sub-optimal for 121 /// classes, e.g. when the \p ND is a member of the base class. 122 /// 123 /// This version considers all the using namespace directives before \p 124 /// InsertionPoint. i.e, if you have `using namespace 125 /// clang::clangd::bar`, this function will return an empty string for the 126 /// example above since no qualification is necessary in that case. 127 /// FIXME: Also take using directives and namespace aliases inside function body 128 /// into account. 129 std::string getQualification(ASTContext &Context, 130 const DeclContext *DestContext, 131 SourceLocation InsertionPoint, 132 const NamedDecl *ND); 133 134 /// This function uses the \p VisibleNamespaces to figure out if a shorter 135 /// qualification is sufficient for \p ND, and ignores any using namespace 136 /// directives. It can be useful if there's no AST for the DestContext, but some 137 /// pseudo-parsing is done. i.e. if \p ND is ns1::ns2::X and \p DestContext is 138 /// ns1::, users can provide `ns2::` as visible to change the result to be 139 /// empty. 140 /// Elements in VisibleNamespaces should be in the form: `ns::`, with trailing 141 /// "::". 142 /// Note that this is just textual and might be incorrect. e.g. when there are 143 /// two namespaces ns1::a and ns2::a, the function will early exit if "a::" is 144 /// present in \p VisibleNamespaces, no matter whether it is from ns1:: or ns2:: 145 std::string getQualification(ASTContext &Context, 146 const DeclContext *DestContext, 147 const NamedDecl *ND, 148 llvm::ArrayRef<std::string> VisibleNamespaces); 149 150 /// Whether we must avoid computing linkage for D during code completion. 151 /// Clang aggressively caches linkage computation, which is stable after the AST 152 /// is built. Unfortunately the AST is incomplete during code completion, so 153 /// linkage may still change. 154 /// 155 /// Example: `auto x = []{^}` at file scope. 156 /// During code completion, the initializer for x hasn't been parsed yet. 157 /// x has type `undeduced auto`, and external linkage. 158 /// If we compute linkage at this point, the external linkage will be cached. 159 /// 160 /// After code completion the initializer is attached, and x has a lambda type. 161 /// This means x has "unique external" linkage. If we computed linkage above, 162 /// the cached value is incorrect. (clang catches this with an assertion). 163 bool hasUnstableLinkage(const Decl *D); 164 165 } // namespace clangd 166 } // namespace clang 167 168 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_AST_H_ 169