1 //===--- APINotesReader.h - API Notes Reader --------------------*- 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 // This file defines the \c APINotesReader class that reads source API notes 10 // data providing additional information about source code as a separate input, 11 // such as the non-nil/nilable annotations for method parameters. 12 // 13 //===----------------------------------------------------------------------===// 14 15 #ifndef LLVM_CLANG_APINOTES_READER_H 16 #define LLVM_CLANG_APINOTES_READER_H 17 18 #include "clang/APINotes/Types.h" 19 #include "llvm/Support/MemoryBuffer.h" 20 #include "llvm/Support/VersionTuple.h" 21 #include <memory> 22 23 namespace clang { 24 namespace api_notes { 25 26 /// A class that reads API notes data from a binary file that was written by 27 /// the \c APINotesWriter. 28 class APINotesReader { 29 class Implementation; 30 std::unique_ptr<Implementation> Implementation; 31 32 APINotesReader(llvm::MemoryBuffer *InputBuffer, 33 llvm::VersionTuple SwiftVersion, bool &Failed); 34 35 public: 36 /// Create a new API notes reader from the given member buffer, which 37 /// contains the contents of a binary API notes file. 38 /// 39 /// \returns the new API notes reader, or null if an error occurred. 40 static std::unique_ptr<APINotesReader> 41 Create(std::unique_ptr<llvm::MemoryBuffer> InputBuffer, 42 llvm::VersionTuple SwiftVersion); 43 44 ~APINotesReader(); 45 46 APINotesReader(const APINotesReader &) = delete; 47 APINotesReader &operator=(const APINotesReader &) = delete; 48 49 /// Captures the completed versioned information for a particular part of 50 /// API notes, including both unversioned API notes and each versioned API 51 /// note for that particular entity. 52 template <typename T> class VersionedInfo { 53 /// The complete set of results. 54 llvm::SmallVector<std::pair<llvm::VersionTuple, T>, 1> Results; 55 56 /// The index of the result that is the "selected" set based on the desired 57 /// Swift version, or null if nothing matched. 58 std::optional<unsigned> Selected; 59 60 public: 61 /// Form an empty set of versioned information. VersionedInfo(std::nullopt_t)62 VersionedInfo(std::nullopt_t) : Selected(std::nullopt) {} 63 64 /// Form a versioned info set given the desired version and a set of 65 /// results. 66 VersionedInfo( 67 llvm::VersionTuple Version, 68 llvm::SmallVector<std::pair<llvm::VersionTuple, T>, 1> Results); 69 70 /// Retrieve the selected index in the result set. getSelected()71 std::optional<unsigned> getSelected() const { return Selected; } 72 73 /// Return the number of versioned results we know about. size()74 unsigned size() const { return Results.size(); } 75 76 /// Access all versioned results. begin()77 const std::pair<llvm::VersionTuple, T> *begin() const { 78 assert(!Results.empty()); 79 return Results.begin(); 80 } end()81 const std::pair<llvm::VersionTuple, T> *end() const { 82 return Results.end(); 83 } 84 85 /// Access a specific versioned result. 86 const std::pair<llvm::VersionTuple, T> &operator[](unsigned index) const { 87 assert(index < Results.size()); 88 return Results[index]; 89 } 90 }; 91 92 /// Look for the context ID of the given Objective-C class. 93 /// 94 /// \param Name The name of the class we're looking for. 95 /// 96 /// \returns The ID, if known. 97 std::optional<ContextID> lookupObjCClassID(llvm::StringRef Name); 98 99 /// Look for information regarding the given Objective-C class. 100 /// 101 /// \param Name The name of the class we're looking for. 102 /// 103 /// \returns The information about the class, if known. 104 VersionedInfo<ContextInfo> lookupObjCClassInfo(llvm::StringRef Name); 105 106 /// Look for the context ID of the given Objective-C protocol. 107 /// 108 /// \param Name The name of the protocol we're looking for. 109 /// 110 /// \returns The ID of the protocol, if known. 111 std::optional<ContextID> lookupObjCProtocolID(llvm::StringRef Name); 112 113 /// Look for information regarding the given Objective-C protocol. 114 /// 115 /// \param Name The name of the protocol we're looking for. 116 /// 117 /// \returns The information about the protocol, if known. 118 VersionedInfo<ContextInfo> lookupObjCProtocolInfo(llvm::StringRef Name); 119 120 /// Look for information regarding the given Objective-C property in 121 /// the given context. 122 /// 123 /// \param CtxID The ID that references the context we are looking for. 124 /// \param Name The name of the property we're looking for. 125 /// \param IsInstance Whether we are looking for an instance property (vs. 126 /// a class property). 127 /// 128 /// \returns Information about the property, if known. 129 VersionedInfo<ObjCPropertyInfo> 130 lookupObjCProperty(ContextID CtxID, llvm::StringRef Name, bool IsInstance); 131 132 /// Look for information regarding the given Objective-C method in 133 /// the given context. 134 /// 135 /// \param CtxID The ID that references the context we are looking for. 136 /// \param Selector The selector naming the method we're looking for. 137 /// \param IsInstanceMethod Whether we are looking for an instance method. 138 /// 139 /// \returns Information about the method, if known. 140 VersionedInfo<ObjCMethodInfo> lookupObjCMethod(ContextID CtxID, 141 ObjCSelectorRef Selector, 142 bool IsInstanceMethod); 143 144 /// Look for information regarding the given C++ method in the given C++ tag 145 /// context. 146 /// 147 /// \param CtxID The ID that references the parent context, i.e. a C++ tag. 148 /// \param Name The name of the C++ method we're looking for. 149 /// 150 /// \returns Information about the method, if known. 151 VersionedInfo<CXXMethodInfo> lookupCXXMethod(ContextID CtxID, 152 llvm::StringRef Name); 153 154 /// Look for information regarding the given global variable. 155 /// 156 /// \param Name The name of the global variable. 157 /// 158 /// \returns information about the global variable, if known. 159 VersionedInfo<GlobalVariableInfo> 160 lookupGlobalVariable(llvm::StringRef Name, 161 std::optional<Context> Ctx = std::nullopt); 162 163 /// Look for information regarding the given global function. 164 /// 165 /// \param Name The name of the global function. 166 /// 167 /// \returns information about the global function, if known. 168 VersionedInfo<GlobalFunctionInfo> 169 lookupGlobalFunction(llvm::StringRef Name, 170 std::optional<Context> Ctx = std::nullopt); 171 172 /// Look for information regarding the given enumerator. 173 /// 174 /// \param Name The name of the enumerator. 175 /// 176 /// \returns information about the enumerator, if known. 177 VersionedInfo<EnumConstantInfo> lookupEnumConstant(llvm::StringRef Name); 178 179 /// Look for the context ID of the given C++ tag. 180 /// 181 /// \param Name The name of the tag we're looking for. 182 /// \param ParentCtx The context in which this tag is declared, e.g. a C++ 183 /// namespace. 184 /// 185 /// \returns The ID, if known. 186 std::optional<ContextID> 187 lookupTagID(llvm::StringRef Name, 188 std::optional<Context> ParentCtx = std::nullopt); 189 190 /// Look for information regarding the given tag 191 /// (struct/union/enum/C++ class). 192 /// 193 /// \param Name The name of the tag. 194 /// 195 /// \returns information about the tag, if known. 196 VersionedInfo<TagInfo> lookupTag(llvm::StringRef Name, 197 std::optional<Context> Ctx = std::nullopt); 198 199 /// Look for information regarding the given typedef. 200 /// 201 /// \param Name The name of the typedef. 202 /// 203 /// \returns information about the typedef, if known. 204 VersionedInfo<TypedefInfo> 205 lookupTypedef(llvm::StringRef Name, 206 std::optional<Context> Ctx = std::nullopt); 207 208 /// Look for the context ID of the given C++ namespace. 209 /// 210 /// \param Name The name of the class we're looking for. 211 /// 212 /// \returns The ID, if known. 213 std::optional<ContextID> 214 lookupNamespaceID(llvm::StringRef Name, 215 std::optional<ContextID> ParentNamespaceID = std::nullopt); 216 }; 217 218 } // end namespace api_notes 219 } // end namespace clang 220 221 #endif // LLVM_CLANG_APINOTES_READER_H 222