clang  15.0.0git
API.cpp
Go to the documentation of this file.
1 //===- ExtractAPI/API.cpp ---------------------------------------*- 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 /// \file
10 /// This file implements the APIRecord and derived record structs,
11 /// and the APISet class.
12 ///
13 //===----------------------------------------------------------------------===//
14 
15 #include "clang/ExtractAPI/API.h"
17 #include "clang/AST/CommentLexer.h"
20 #include "llvm/ADT/STLFunctionalExtras.h"
21 #include "llvm/ADT/StringRef.h"
22 #include <memory>
23 
24 using namespace clang::extractapi;
25 using namespace llvm;
26 
27 namespace {
28 
29 template <typename RecordTy, typename... CtorArgsTy>
30 RecordTy *addTopLevelRecord(APISet::RecordMap<RecordTy> &RecordMap,
31  StringRef USR, CtorArgsTy &&...CtorArgs) {
32  auto Result = RecordMap.insert({USR, nullptr});
33 
34  // Create the record if it does not already exist
35  if (Result.second)
36  Result.first->second =
37  std::make_unique<RecordTy>(USR, std::forward<CtorArgsTy>(CtorArgs)...);
38 
39  return Result.first->second.get();
40 }
41 
42 } // namespace
43 
45 APISet::addGlobalVar(StringRef Name, StringRef USR, PresumedLoc Loc,
46  const AvailabilityInfo &Availability, LinkageInfo Linkage,
47  const DocComment &Comment, DeclarationFragments Fragments,
48  DeclarationFragments SubHeading) {
49  return addTopLevelRecord(GlobalVariables, USR, Name, Loc, Availability,
50  Linkage, Comment, Fragments, SubHeading);
51 }
52 
54  StringRef Name, StringRef USR, PresumedLoc Loc,
55  const AvailabilityInfo &Availability, LinkageInfo Linkage,
56  const DocComment &Comment, DeclarationFragments Fragments,
57  DeclarationFragments SubHeading, FunctionSignature Signature) {
58  return addTopLevelRecord(GlobalFunctions, USR, Name, Loc, Availability,
59  Linkage, Comment, Fragments, SubHeading, Signature);
60 }
61 
63  EnumRecord *Enum, StringRef Name, StringRef USR, PresumedLoc Loc,
64  const AvailabilityInfo &Availability, const DocComment &Comment,
65  DeclarationFragments Declaration, DeclarationFragments SubHeading) {
66  auto Record = std::make_unique<EnumConstantRecord>(
67  USR, Name, Loc, Availability, Comment, Declaration, SubHeading);
68  return Enum->Constants.emplace_back(std::move(Record)).get();
69 }
70 
71 EnumRecord *APISet::addEnum(StringRef Name, StringRef USR, PresumedLoc Loc,
72  const AvailabilityInfo &Availability,
73  const DocComment &Comment,
74  DeclarationFragments Declaration,
75  DeclarationFragments SubHeading) {
76  return addTopLevelRecord(Enums, USR, Name, Loc, Availability, Comment,
77  Declaration, SubHeading);
78 }
79 
81  StringRef USR, PresumedLoc Loc,
82  const AvailabilityInfo &Availability,
83  const DocComment &Comment,
84  DeclarationFragments Declaration,
85  DeclarationFragments SubHeading) {
86  auto Record = std::make_unique<StructFieldRecord>(
87  USR, Name, Loc, Availability, Comment, Declaration, SubHeading);
88  return Struct->Fields.emplace_back(std::move(Record)).get();
89 }
90 
91 StructRecord *APISet::addStruct(StringRef Name, StringRef USR, PresumedLoc Loc,
92  const AvailabilityInfo &Availability,
93  const DocComment &Comment,
94  DeclarationFragments Declaration,
95  DeclarationFragments SubHeading) {
96  return addTopLevelRecord(Structs, USR, Name, Loc, Availability, Comment,
97  Declaration, SubHeading);
98 }
99 
101  StringRef Name, StringRef USR, PresumedLoc Loc,
102  const AvailabilityInfo &Availability, const DocComment &Comment,
103  DeclarationFragments Declaration, DeclarationFragments SubHeading,
104  SymbolReference Interface) {
105  // Create the category record.
106  auto *Record = addTopLevelRecord(ObjCCategories, USR, Name, Loc, Availability,
107  Comment, Declaration, SubHeading, Interface);
108 
109  // If this category is extending a known interface, associate it with the
110  // ObjCInterfaceRecord.
111  auto It = ObjCInterfaces.find(Interface.USR);
112  if (It != ObjCInterfaces.end())
113  It->second->Categories.push_back(Record);
114 
115  return Record;
116 }
117 
119  StringRef Name, StringRef USR, PresumedLoc Loc,
120  const AvailabilityInfo &Availability, LinkageInfo Linkage,
121  const DocComment &Comment, DeclarationFragments Declaration,
122  DeclarationFragments SubHeading, SymbolReference SuperClass) {
123  return addTopLevelRecord(ObjCInterfaces, USR, Name, Loc, Availability,
124  Linkage, Comment, Declaration, SubHeading,
125  SuperClass);
126 }
127 
129  ObjCContainerRecord *Container, StringRef Name, StringRef USR,
130  PresumedLoc Loc, const AvailabilityInfo &Availability,
131  const DocComment &Comment, DeclarationFragments Declaration,
132  DeclarationFragments SubHeading, FunctionSignature Signature,
133  bool IsInstanceMethod) {
134  auto Record = std::make_unique<ObjCMethodRecord>(
135  USR, Name, Loc, Availability, Comment, Declaration, SubHeading, Signature,
136  IsInstanceMethod);
137  return Container->Methods.emplace_back(std::move(Record)).get();
138 }
139 
141  ObjCContainerRecord *Container, StringRef Name, StringRef USR,
142  PresumedLoc Loc, const AvailabilityInfo &Availability,
143  const DocComment &Comment, DeclarationFragments Declaration,
144  DeclarationFragments SubHeading,
145  ObjCPropertyRecord::AttributeKind Attributes, StringRef GetterName,
146  StringRef SetterName, bool IsOptional) {
147  auto Record = std::make_unique<ObjCPropertyRecord>(
148  USR, Name, Loc, Availability, Comment, Declaration, SubHeading,
149  Attributes, GetterName, SetterName, IsOptional);
150  return Container->Properties.emplace_back(std::move(Record)).get();
151 }
152 
154  ObjCContainerRecord *Container, StringRef Name, StringRef USR,
155  PresumedLoc Loc, const AvailabilityInfo &Availability,
156  const DocComment &Comment, DeclarationFragments Declaration,
157  DeclarationFragments SubHeading,
159  auto Record = std::make_unique<ObjCInstanceVariableRecord>(
160  USR, Name, Loc, Availability, Comment, Declaration, SubHeading, Access);
161  return Container->Ivars.emplace_back(std::move(Record)).get();
162 }
163 
165  StringRef Name, StringRef USR, PresumedLoc Loc,
166  const AvailabilityInfo &Availability, const DocComment &Comment,
167  DeclarationFragments Declaration, DeclarationFragments SubHeading) {
168  return addTopLevelRecord(ObjCProtocols, USR, Name, Loc, Availability, Comment,
169  Declaration, SubHeading);
170 }
171 
173 APISet::addMacroDefinition(StringRef Name, StringRef USR, PresumedLoc Loc,
174  DeclarationFragments Declaration,
175  DeclarationFragments SubHeading) {
176  return addTopLevelRecord(Macros, USR, Name, Loc, Declaration, SubHeading);
177 }
178 
179 TypedefRecord *APISet::addTypedef(StringRef Name, StringRef USR,
180  PresumedLoc Loc,
181  const AvailabilityInfo &Availability,
182  const DocComment &Comment,
183  DeclarationFragments Declaration,
184  DeclarationFragments SubHeading,
185  SymbolReference UnderlyingType) {
186  return addTopLevelRecord(Typedefs, USR, Name, Loc, Availability, Comment,
187  Declaration, SubHeading, UnderlyingType);
188 }
189 
190 StringRef APISet::recordUSR(const Decl *D) {
191  SmallString<128> USR;
193  return copyString(USR);
194 }
195 
196 StringRef APISet::recordUSRForMacro(StringRef Name, SourceLocation SL,
197  const SourceManager &SM) {
198  SmallString<128> USR;
199  index::generateUSRForMacro(Name, SL, SM, USR);
200  return copyString(USR);
201 }
202 
203 StringRef APISet::copyString(StringRef String) {
204  if (String.empty())
205  return {};
206 
207  // No need to allocate memory and copy if the string has already been stored.
208  if (StringAllocator.identifyObject(String.data()))
209  return String;
210 
211  void *Ptr = StringAllocator.Allocate(String.size(), 1);
212  memcpy(Ptr, String.data(), String.size());
213  return StringRef(reinterpret_cast<const char *>(Ptr), String.size());
214 }
215 
217 
219 
220 void GlobalFunctionRecord::anchor() {}
221 void GlobalVariableRecord::anchor() {}
222 void EnumConstantRecord::anchor() {}
223 void EnumRecord::anchor() {}
224 void StructFieldRecord::anchor() {}
225 void StructRecord::anchor() {}
226 void ObjCPropertyRecord::anchor() {}
227 void ObjCInstanceVariableRecord::anchor() {}
228 void ObjCMethodRecord::anchor() {}
229 void ObjCCategoryRecord::anchor() {}
230 void ObjCInterfaceRecord::anchor() {}
231 void ObjCProtocolRecord::anchor() {}
232 void MacroDefinitionRecord::anchor() {}
233 void TypedefRecord::anchor() {}
clang::extractapi::APISet::addObjCInstanceVariable
ObjCInstanceVariableRecord * addObjCInstanceVariable(ObjCContainerRecord *Container, StringRef Name, StringRef USR, PresumedLoc Loc, const AvailabilityInfo &Availability, const DocComment &Comment, DeclarationFragments Declaration, DeclarationFragments SubHeading, ObjCInstanceVariableRecord::AccessControl Access)
Create and add an Objective-C instance variable record into the API set.
Definition: API.cpp:153
llvm
YAML serialization mapping.
Definition: Dominators.h:30
clang::extractapi::StructRecord
This holds information associated with structs.
Definition: API.h:210
clang::extractapi::ObjCProtocolRecord
This holds information associated with Objective-C protocols.
Definition: API.h:401
clang::extractapi::ObjCMethodRecord
This holds information associated with Objective-C methods.
Definition: API.h:291
clang::SourceLocation
Encodes a location in the source.
Definition: SourceLocation.h:86
clang::extractapi::GlobalVariableRecord
This holds information associated with global functions.
Definition: API.h:139
memcpy
__DEVICE__ void * memcpy(void *__a, const void *__b, size_t __c)
Definition: __clang_cuda_device_functions.h:1549
clang::extractapi::DeclarationFragments
DeclarationFragments is a vector of tagged important parts of a symbol's declaration.
Definition: DeclarationFragments.h:43
clang::extractapi::APISet::addEnum
EnumRecord * addEnum(StringRef Name, StringRef USR, PresumedLoc Loc, const AvailabilityInfo &Availability, const DocComment &Comment, DeclarationFragments Declaration, DeclarationFragments SubHeading)
Create and add an enum record into the API set.
Definition: API.cpp:71
clang::extractapi::FunctionSignature
Store function signature information with DeclarationFragments of the return type and parameters.
Definition: DeclarationFragments.h:147
clang::SourceManager
This class handles loading and caching of source files into memory.
Definition: SourceManager.h:627
clang::ObjCIvarDecl::AccessControl
AccessControl
Definition: DeclObjC.h:1927
RawCommentList.h
clang::extractapi::GlobalFunctionRecord
This holds information associated with global functions.
Definition: API.h:117
clang::extractapi::APIRecord::~APIRecord
virtual ~APIRecord()=0
Definition: API.cpp:216
clang::Linkage
Linkage
Describes the different kinds of linkage (C++ [basic.link], C99 6.2.2) that an entity may have.
Definition: Linkage.h:23
clang::extractapi::APISet::addGlobalFunction
GlobalFunctionRecord * addGlobalFunction(StringRef Name, StringRef USR, PresumedLoc Loc, const AvailabilityInfo &Availability, LinkageInfo Linkage, const DocComment &Comment, DeclarationFragments Declaration, DeclarationFragments SubHeading, FunctionSignature Signature)
Create and add a function record into the API set.
Definition: API.cpp:53
clang::extractapi::TypedefRecord
This holds information associated with typedefs.
Definition: API.h:440
clang::extractapi
Definition: API.h:36
clang::extractapi::MacroDefinitionRecord
This holds information associated with macro definitions.
Definition: API.h:420
clang::extractapi::APISet::recordUSR
StringRef recordUSR(const Decl *D)
Generate and store the USR of declaration D.
Definition: API.cpp:190
clang::extractapi::APISet::copyString
StringRef copyString(StringRef String)
Copy String into the Allocator in this APISet.
Definition: API.cpp:203
clang::extractapi::SymbolReference::USR
StringRef USR
Definition: API.h:316
llvm::SmallString< 128 >
clang::extractapi::ObjCInstanceVariableRecord
This holds information associated with Objective-C instance variables.
Definition: API.h:268
clang::extractapi::APISet::recordUSRForMacro
StringRef recordUSRForMacro(StringRef Name, SourceLocation SL, const SourceManager &SM)
Generate and store the USR for a macro Name.
Definition: API.cpp:196
clang::LinkageInfo
Definition: Visibility.h:52
clang::extractapi::DocComment
std::vector< RawComment::CommentLine > DocComment
DocComment is a vector of RawComment::CommentLine.
Definition: API.h:51
clang::extractapi::APISet::addStructField
StructFieldRecord * addStructField(StructRecord *Struct, StringRef Name, StringRef USR, PresumedLoc Loc, const AvailabilityInfo &Availability, const DocComment &Comment, DeclarationFragments Declaration, DeclarationFragments SubHeading)
Create and add a struct field record into the API set.
Definition: API.cpp:80
clang::extractapi::APISet::addGlobalVar
GlobalVariableRecord * addGlobalVar(StringRef Name, StringRef USR, PresumedLoc Loc, const AvailabilityInfo &Availability, LinkageInfo Linkage, const DocComment &Comment, DeclarationFragments Declaration, DeclarationFragments SubHeading)
Create and add a global variable record into the API set.
Definition: API.cpp:45
clang::extractapi::AvailabilityInfo
Stores availability attributes of a symbol.
Definition: AvailabilityInfo.h:28
clang::Decl
Decl - This represents one declaration (or definition), e.g.
Definition: DeclBase.h:83
USRGeneration.h
clang::extractapi::ObjCContainerRecord
The base representation of an Objective-C container record.
Definition: API.h:335
clang::extractapi::APISet::addObjCProperty
ObjCPropertyRecord * addObjCProperty(ObjCContainerRecord *Container, StringRef Name, StringRef USR, PresumedLoc Loc, const AvailabilityInfo &Availability, const DocComment &Comment, DeclarationFragments Declaration, DeclarationFragments SubHeading, ObjCPropertyRecord::AttributeKind Attributes, StringRef GetterName, StringRef SetterName, bool IsOptional)
Create and add an Objective-C property record into the API set.
Definition: API.cpp:140
clang::extractapi::APISet::addMacroDefinition
MacroDefinitionRecord * addMacroDefinition(StringRef Name, StringRef USR, PresumedLoc Loc, DeclarationFragments Declaration, DeclarationFragments SubHeading)
Create a macro definition record into the API set.
Definition: API.cpp:173
clang::extractapi::APISet::addObjCCategory
ObjCCategoryRecord * addObjCCategory(StringRef Name, StringRef USR, PresumedLoc Loc, const AvailabilityInfo &Availability, const DocComment &Comment, DeclarationFragments Declaration, DeclarationFragments SubHeading, SymbolReference Interface)
Create and add an Objective-C category record into the API set.
Definition: API.cpp:100
clang::extractapi::ObjCPropertyRecord
This holds information associated with Objective-C properties.
Definition: API.h:229
API.h
clang::extractapi::EnumRecord
This holds information associated with enums.
Definition: API.h:175
clang::extractapi::APISet::addObjCProtocol
ObjCProtocolRecord * addObjCProtocol(StringRef Name, StringRef USR, PresumedLoc Loc, const AvailabilityInfo &Availability, const DocComment &Comment, DeclarationFragments Declaration, DeclarationFragments SubHeading)
Create and add an Objective-C protocol record into the API set.
Definition: API.cpp:164
clang::index::generateUSRForDecl
bool generateUSRForDecl(const Decl *D, SmallVectorImpl< char > &Buf)
Generate a USR for a Decl, including the USR prefix.
Definition: USRGeneration.cpp:1088
clang::extractapi::APISet::addEnumConstant
EnumConstantRecord * addEnumConstant(EnumRecord *Enum, StringRef Name, StringRef USR, PresumedLoc Loc, const AvailabilityInfo &Availability, const DocComment &Comment, DeclarationFragments Declaration, DeclarationFragments SubHeading)
Create and add an enum constant record into the API set.
Definition: API.cpp:62
clang::extractapi::ObjCCategoryRecord
This holds information associated with Objective-C categories.
Definition: API.h:355
clang::extractapi::ObjCInterfaceRecord
This holds information associated with Objective-C interfaces/classes.
Definition: API.h:377
clang::extractapi::EnumConstantRecord
This holds information associated with enum constants.
Definition: API.h:157
clang::extractapi::StructFieldRecord
This holds information associated with struct fields.
Definition: API.h:193
clang::index::generateUSRForMacro
bool generateUSRForMacro(const MacroDefinitionRecord *MD, const SourceManager &SM, SmallVectorImpl< char > &Buf)
Generate a USR for a macro, including the USR prefix.
Definition: USRGeneration.cpp:1101
clang::PresumedLoc
Represents an unpacked "presumed" location which can be presented to the user.
Definition: SourceLocation.h:302
clang::extractapi::APISet::addObjCInterface
ObjCInterfaceRecord * addObjCInterface(StringRef Name, StringRef USR, PresumedLoc Loc, const AvailabilityInfo &Availability, LinkageInfo Linkage, const DocComment &Comment, DeclarationFragments Declaration, DeclarationFragments SubHeading, SymbolReference SuperClass)
Create and add an Objective-C interface record into the API set.
Definition: API.cpp:118
clang::extractapi::APISet::addStruct
StructRecord * addStruct(StringRef Name, StringRef USR, PresumedLoc Loc, const AvailabilityInfo &Availability, const DocComment &Comment, DeclarationFragments Declaration, DeclarationFragments SubHeading)
Create and add a struct record into the API set.
Definition: API.cpp:91
clang::extractapi::ObjCPropertyRecord::AttributeKind
AttributeKind
The attributes associated with an Objective-C property.
Definition: API.h:231
clang::extractapi::APISet::addObjCMethod
ObjCMethodRecord * addObjCMethod(ObjCContainerRecord *Container, StringRef Name, StringRef USR, PresumedLoc Loc, const AvailabilityInfo &Availability, const DocComment &Comment, DeclarationFragments Declaration, DeclarationFragments SubHeading, FunctionSignature Signature, bool IsInstanceMethod)
Create and add an Objective-C method record into the API set.
Definition: API.cpp:128
SM
#define SM(sm)
Definition: Cuda.cpp:81
clang::extractapi::APISet::RecordMap
llvm::MapVector< StringRef, std::unique_ptr< RecordTy > > RecordMap
A mapping type to store a set of APIRecords with the USR as the key.
Definition: API.h:654
CommentCommandTraits.h
clang::extractapi::APISet::addTypedef
TypedefRecord * addTypedef(StringRef Name, StringRef USR, PresumedLoc Loc, const AvailabilityInfo &Availability, const DocComment &Comment, DeclarationFragments Declaration, DeclarationFragments SubHeading, SymbolReference UnderlyingType)
Create a typedef record into the API set.
Definition: API.cpp:179
copyString
static const char * copyString(StringRef Str, llvm::BumpPtrAllocator &Alloc)
Definition: HeaderSearch.cpp:743
clang::extractapi::SymbolReference
This represents a reference to another symbol that might come from external sources.
Definition: API.h:314
CommentLexer.h
clang::extractapi::ObjCContainerRecord::~ObjCContainerRecord
virtual ~ObjCContainerRecord()=0
Definition: API.cpp:218