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/DeclObjC.h" 19 #include "clang/AST/NestedNameSpecifier.h" 20 #include "clang/Basic/SourceLocation.h" 21 #include "clang/Lex/MacroInfo.h" 22 #include "llvm/ADT/DenseSet.h" 23 #include "llvm/ADT/StringRef.h" 24 #include <string> 25 #include <vector> 26 27 namespace clang { 28 class SourceManager; 29 class Decl; 30 31 namespace clangd { 32 33 /// Returns true if the declaration is considered implementation detail based on 34 /// heuristics. For example, a declaration whose name is not explicitly spelled 35 /// in code is considered implementation detail. 36 bool isImplementationDetail(const Decl *D); 37 38 /// Find the source location of the identifier for \p D. 39 /// Transforms macro locations to locations spelled inside files. All code 40 /// that needs locations of declaration names (e.g. the index) should go through 41 /// this function. 42 SourceLocation nameLocation(const clang::Decl &D, const SourceManager &SM); 43 44 /// Returns the qualified name of ND. The scope doesn't contain unwritten scopes 45 /// like inline namespaces. 46 std::string printQualifiedName(const NamedDecl &ND); 47 48 /// Returns the first enclosing namespace scope starting from \p DC. 49 std::string printNamespaceScope(const DeclContext &DC); 50 51 /// Returns the name of the namespace inside the 'using namespace' directive, as 52 /// written in the code. E.g., passing 'using namespace ::std' will result in 53 /// '::std'. 54 std::string printUsingNamespaceName(const ASTContext &Ctx, 55 const UsingDirectiveDecl &D); 56 57 /// Prints unqualified name of the decl for the purpose of displaying it to the 58 /// user. Anonymous decls return names of the form "(anonymous {kind})", e.g. 59 /// "(anonymous struct)" or "(anonymous namespace)". 60 std::string printName(const ASTContext &Ctx, const NamedDecl &ND); 61 62 /// Prints template arguments of a decl as written in the source code, including 63 /// enclosing '<' and '>', e.g for a partial specialization like: template 64 /// <typename U> struct Foo<int, U> will return '<int, U>'. Returns an empty 65 /// string if decl is not a template specialization. 66 std::string printTemplateSpecializationArgs(const NamedDecl &ND); 67 68 /// Print the Objective-C method name, including the full container name, e.g. 69 /// `-[MyClass(Category) method:]` 70 std::string printObjCMethod(const ObjCMethodDecl &Method); 71 72 /// Print the Objective-C container name including categories, e.g. `MyClass`, 73 // `MyClass()`, `MyClass(Category)`, and `MyProtocol`. 74 std::string printObjCContainer(const ObjCContainerDecl &C); 75 76 /// Gets the symbol ID for a declaration. Returned SymbolID might be null. 77 SymbolID getSymbolID(const Decl *D); 78 79 /// Gets the symbol ID for a macro. Returned SymbolID might be null. 80 /// Currently, this is an encoded USR of the macro, which incorporates macro 81 /// locations (e.g. file name, offset in file). 82 /// FIXME: the USR semantics might not be stable enough as the ID for index 83 /// macro (e.g. a change in definition offset can result in a different USR). We 84 /// could change these semantics in the future by reimplementing this funcure 85 /// (e.g. avoid USR for macros). 86 SymbolID getSymbolID(const llvm::StringRef MacroName, const MacroInfo *MI, 87 const SourceManager &SM); 88 89 /// Returns a QualType as string. The result doesn't contain unwritten scopes 90 /// like anonymous/inline namespace. 91 std::string printType(const QualType QT, const DeclContext &CurContext); 92 93 /// Indicates if \p D is a template instantiation implicitly generated by the 94 /// compiler, e.g. 95 /// template <class T> struct vector {}; 96 /// vector<int> v; // 'vector<int>' is an implicit instantiation 97 bool isImplicitTemplateInstantiation(const NamedDecl *D); 98 /// Indicates if \p D is an explicit template specialization, e.g. 99 /// template <class T> struct vector {}; 100 /// template <> struct vector<bool> {}; // <-- explicit specialization 101 /// 102 /// Note that explicit instantiations are NOT explicit specializations, albeit 103 /// they look similar. 104 /// template struct vector<bool>; // <-- explicit instantiation, NOT an 105 /// explicit specialization. 106 bool isExplicitTemplateSpecialization(const NamedDecl *D); 107 108 /// Returns a nested name specifier loc of \p ND if it was present in the 109 /// source, e.g. 110 /// void ns::something::foo() -> returns 'ns::something' 111 /// void foo() -> returns null 112 NestedNameSpecifierLoc getQualifierLoc(const NamedDecl &ND); 113 114 // Returns a type corresponding to a declaration of that type. 115 // Unlike the method on ASTContext, attempts to preserve the type as-written 116 // (i.e. vector<T*> rather than vector<type-parameter-0-0 *>. 117 QualType declaredType(const TypeDecl *D); 118 119 /// Retrieves the deduced type at a given location (auto, decltype). 120 /// It will return the underlying type. 121 /// If the type is an undeduced auto, returns the type itself. 122 llvm::Optional<QualType> getDeducedType(ASTContext &, SourceLocation Loc); 123 124 /// Gets the nested name specifier necessary for spelling \p ND in \p 125 /// DestContext, at \p InsertionPoint. It selects the shortest suffix of \p ND 126 /// such that it is visible in \p DestContext. 127 /// Returns an empty string if no qualification is necessary. For example, if 128 /// you want to qualify clang::clangd::bar::foo in clang::clangd::x, this 129 /// function will return bar. Note that the result might be sub-optimal for 130 /// classes, e.g. when the \p ND is a member of the base class. 131 /// 132 /// This version considers all the using namespace directives before \p 133 /// InsertionPoint. i.e, if you have `using namespace 134 /// clang::clangd::bar`, this function will return an empty string for the 135 /// example above since no qualification is necessary in that case. 136 /// FIXME: Also take using directives and namespace aliases inside function body 137 /// into account. 138 std::string getQualification(ASTContext &Context, 139 const DeclContext *DestContext, 140 SourceLocation InsertionPoint, 141 const NamedDecl *ND); 142 143 /// This function uses the \p VisibleNamespaces to figure out if a shorter 144 /// qualification is sufficient for \p ND, and ignores any using namespace 145 /// directives. It can be useful if there's no AST for the DestContext, but some 146 /// pseudo-parsing is done. i.e. if \p ND is ns1::ns2::X and \p DestContext is 147 /// ns1::, users can provide `ns2::` as visible to change the result to be 148 /// empty. 149 /// Elements in VisibleNamespaces should be in the form: `ns::`, with trailing 150 /// "::". 151 /// Note that this is just textual and might be incorrect. e.g. when there are 152 /// two namespaces ns1::a and ns2::a, the function will early exit if "a::" is 153 /// present in \p VisibleNamespaces, no matter whether it is from ns1:: or ns2:: 154 std::string getQualification(ASTContext &Context, 155 const DeclContext *DestContext, 156 const NamedDecl *ND, 157 llvm::ArrayRef<std::string> VisibleNamespaces); 158 159 /// Whether we must avoid computing linkage for D during code completion. 160 /// Clang aggressively caches linkage computation, which is stable after the AST 161 /// is built. Unfortunately the AST is incomplete during code completion, so 162 /// linkage may still change. 163 /// 164 /// Example: `auto x = []{^}` at file scope. 165 /// During code completion, the initializer for x hasn't been parsed yet. 166 /// x has type `undeduced auto`, and external linkage. 167 /// If we compute linkage at this point, the external linkage will be cached. 168 /// 169 /// After code completion the initializer is attached, and x has a lambda type. 170 /// This means x has "unique external" linkage. If we computed linkage above, 171 /// the cached value is incorrect. (clang catches this with an assertion). 172 bool hasUnstableLinkage(const Decl *D); 173 174 /// Checks whether \p D is more than \p MaxDepth away from translation unit 175 /// scope. 176 /// This is useful for limiting traversals to keep operation latencies 177 /// reasonable. 178 bool isDeeplyNested(const Decl *D, unsigned MaxDepth = 10); 179 180 } // namespace clangd 181 } // namespace clang 182 183 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_AST_H_ 184