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