clang 19.0.0git
SymbolGraphSerializer.h
Go to the documentation of this file.
1//===- ExtractAPI/Serialization/SymbolGraphSerializer.h ---------*- 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 defines the SymbolGraphSerializer class.
11///
12/// Implement an APISetVisitor to serialize the APISet into the Symbol Graph
13/// format for ExtractAPI. See https://github.com/apple/swift-docc-symbolkit.
14///
15//===----------------------------------------------------------------------===//
16
17#ifndef LLVM_CLANG_EXTRACTAPI_SERIALIZATION_SYMBOLGRAPHSERIALIZER_H
18#define LLVM_CLANG_EXTRACTAPI_SERIALIZATION_SYMBOLGRAPHSERIALIZER_H
19
23#include "llvm/ADT/SmallVector.h"
24#include "llvm/ADT/StringSet.h"
25#include "llvm/Support/JSON.h"
26#include "llvm/Support/VersionTuple.h"
27#include "llvm/Support/raw_ostream.h"
28#include <optional>
29
30namespace clang {
31namespace extractapi {
32
33using namespace llvm::json;
34
35/// Common options to customize the visitor output.
37 /// Do not include unnecessary whitespaces to save space.
38 bool Compact;
39};
40
41/// The visitor that organizes API information in the Symbol Graph format.
42///
43/// The Symbol Graph format (https://github.com/apple/swift-docc-symbolkit)
44/// models an API set as a directed graph, where nodes are symbol declarations,
45/// and edges are relationships between the connected symbols.
46class SymbolGraphSerializer : public APISetVisitor<SymbolGraphSerializer> {
47 /// A JSON array of formatted symbols in \c APISet.
48 Array Symbols;
49
50 /// A JSON array of formatted symbol relationships in \c APISet.
51 Array Relationships;
52
53 /// The Symbol Graph format version used by this serializer.
54 static const VersionTuple FormatVersion;
55
56 /// Indicates whether child symbols should be visited. This is mainly
57 /// useful for \c serializeSingleSymbolSGF.
58 bool ShouldRecurse;
59
60public:
61 /// Serialize the APIs in \c APISet in the Symbol Graph format.
62 ///
63 /// \returns a JSON object that contains the root of the formatted
64 /// Symbol Graph.
65 Object serialize();
66
67 /// Wrap serialize(void) and write out the serialized JSON object to \p os.
68 void serialize(raw_ostream &os);
69
70 /// Serialize a single symbol SGF. This is primarily used for libclang.
71 ///
72 /// \returns an optional JSON Object representing the payload that libclang
73 /// expects for providing symbol information for a single symbol. If this is
74 /// not a known symbol returns \c std::nullopt.
75 static std::optional<Object> serializeSingleSymbolSGF(StringRef USR,
76 const APISet &API);
77
78 /// The kind of a relationship between two symbols.
80 /// The source symbol is a member of the target symbol.
81 /// For example enum constants are members of the enum, class/instance
82 /// methods are members of the class, etc.
84
85 /// The source symbol is inherited from the target symbol.
87
88 /// The source symbol conforms to the target symbol.
89 /// For example Objective-C protocol conformances.
91
92 /// The source symbol is an extension to the target symbol.
93 /// For example Objective-C categories extending an external type.
95 };
96
97 /// Get the string representation of the relationship kind.
98 static StringRef getRelationshipString(RelationshipKind Kind);
99
101
102 static StringRef getConstraintString(ConstraintKind Kind);
103
104private:
105 /// Just serialize the currently recorded objects in Symbol Graph format.
106 Object serializeCurrentGraph();
107
108 /// Synthesize the metadata section of the Symbol Graph format.
109 ///
110 /// The metadata section describes information about the Symbol Graph itself,
111 /// including the format version and the generator information.
112 Object serializeMetadata() const;
113
114 /// Synthesize the module section of the Symbol Graph format.
115 ///
116 /// The module section contains information about the product that is defined
117 /// by the given API set.
118 /// Note that "module" here is not to be confused with the Clang/C++ module
119 /// concept.
120 Object serializeModule() const;
121
122 /// Determine if the given \p Record should be skipped during serialization.
123 bool shouldSkip(const APIRecord &Record) const;
124
125 /// Format the common API information for \p Record.
126 ///
127 /// This handles the shared information of all kinds of API records,
128 /// for example identifier and source location. The resulting object is then
129 /// augmented with kind-specific symbol information by the caller.
130 /// This method also checks if the given \p Record should be skipped during
131 /// serialization.
132 ///
133 /// \returns \c std::nullopt if this \p Record should be skipped, or a JSON
134 /// object containing common symbol information of \p Record.
135 template <typename RecordTy>
136 std::optional<Object> serializeAPIRecord(const RecordTy &Record) const;
137
138 /// Helper method to serialize second-level member records of \p Record and
139 /// the member-of relationships.
140 template <typename MemberTy>
141 void serializeMembers(const APIRecord &Record,
142 const SmallVector<std::unique_ptr<MemberTy>> &Members);
143
144 /// Serialize the \p Kind relationship between \p Source and \p Target.
145 ///
146 /// Record the relationship between the two symbols in
147 /// SymbolGraphSerializer::Relationships.
148 void serializeRelationship(RelationshipKind Kind, SymbolReference Source,
150
151protected:
152 /// The list of symbols to ignore.
153 ///
154 /// Note: This should be consulted before emitting a symbol.
156
158
159 llvm::StringSet<> visitedCategories;
160
161public:
162 void visitNamespaceRecord(const NamespaceRecord &Record);
163
164 /// Visit a global function record.
166
167 /// Visit a global variable record.
169
170 /// Visit an enum record.
171 void visitEnumRecord(const EnumRecord &Record);
172
173 /// Visit a record record.
174 void visitRecordRecord(const RecordRecord &Record);
175
176 void visitStaticFieldRecord(const StaticFieldRecord &Record);
177
178 void visitCXXClassRecord(const CXXClassRecord &Record);
179
181
184
187
189
191
193
196
197 void visitCXXFieldRecord(const CXXFieldRecord &Record);
198
200
201 void visitConceptRecord(const ConceptRecord &Record);
202
203 void
205
208
211
212 void
214
217
218 /// Visit an Objective-C container record.
220
221 /// Visit an Objective-C category record.
223
224 /// Visit a macro definition record.
226
227 /// Visit a typedef record.
228 void visitTypedefRecord(const TypedefRecord &Record);
229
230 /// Serialize a single record.
231 void serializeSingleRecord(const APIRecord *Record);
232
235 bool ShouldRecurse = true)
236 : APISetVisitor(API), ShouldRecurse(ShouldRecurse),
238};
239
240} // namespace extractapi
241} // namespace clang
242
243#endif // LLVM_CLANG_EXTRACTAPI_SERIALIZATION_SYMBOLGRAPHSERIALIZER_H
This file defines the APIRecord-based structs and the APISet class.
This file defines the ExtractAPI APISetVisitor interface.
The base interface of visitors for API information.
APISet holds the set of API records collected from given inputs.
Definition: API.h:1193
The visitor that organizes API information in the Symbol Graph format.
void visitGlobalVariableTemplateSpecializationRecord(const GlobalVariableTemplateSpecializationRecord &Record)
static StringRef getRelationshipString(RelationshipKind Kind)
Get the string representation of the relationship kind.
void visitCXXClassRecord(const CXXClassRecord &Record)
void visitGlobalVariableTemplatePartialSpecializationRecord(const GlobalVariableTemplatePartialSpecializationRecord &Record)
const APIIgnoresList & IgnoresList
The list of symbols to ignore.
void visitCXXFieldRecord(const CXXFieldRecord &Record)
void visitObjCContainerRecord(const ObjCContainerRecord &Record)
Visit an Objective-C container record.
SymbolGraphSerializer(const APISet &API, const APIIgnoresList &IgnoresList, SymbolGraphSerializerOption Options={}, bool ShouldRecurse=true)
void visitMacroDefinitionRecord(const MacroDefinitionRecord &Record)
Visit a macro definition record.
void visitCXXFieldTemplateRecord(const CXXFieldTemplateRecord &Record)
void visitEnumRecord(const EnumRecord &Record)
Visit an enum record.
void visitGlobalVariableTemplateRecord(const GlobalVariableTemplateRecord &Record)
Object serialize()
Serialize the APIs in APISet in the Symbol Graph format.
void visitTypedefRecord(const TypedefRecord &Record)
Visit a typedef record.
void serializeSingleRecord(const APIRecord *Record)
Serialize a single record.
RelationshipKind
The kind of a relationship between two symbols.
@ InheritsFrom
The source symbol is inherited from the target symbol.
@ MemberOf
The source symbol is a member of the target symbol.
@ ExtensionTo
The source symbol is an extension to the target symbol.
@ ConformsTo
The source symbol conforms to the target symbol.
void visitGlobalFunctionRecord(const GlobalFunctionRecord &Record)
Visit a global function record.
void visitObjCCategoryRecord(const ObjCCategoryRecord &Record)
Visit an Objective-C category record.
void visitClassTemplateSpecializationRecord(const ClassTemplateSpecializationRecord &Record)
void visitConceptRecord(const ConceptRecord &Record)
void visitGlobalFunctionTemplateSpecializationRecord(const GlobalFunctionTemplateSpecializationRecord &Record)
void visitStaticFieldRecord(const StaticFieldRecord &Record)
void visitGlobalFunctionTemplateRecord(const GlobalFunctionTemplateRecord &Record)
static StringRef getConstraintString(ConstraintKind Kind)
void visitCXXStaticMethodRecord(const CXXStaticMethodRecord &Record)
void visitClassTemplateRecord(const ClassTemplateRecord &Record)
void visitClassTemplatePartialSpecializationRecord(const ClassTemplatePartialSpecializationRecord &Record)
void visitMethodTemplateRecord(const CXXMethodTemplateRecord &Record)
static std::optional< Object > serializeSingleSymbolSGF(StringRef USR, const APISet &API)
Serialize a single symbol SGF.
void visitGlobalVariableRecord(const GlobalVariableRecord &Record)
Visit a global variable record.
void visitCXXInstanceMethodRecord(const CXXInstanceMethodRecord &Record)
void visitMethodTemplateSpecializationRecord(const CXXMethodTemplateSpecializationRecord &Record)
void visitNamespaceRecord(const NamespaceRecord &Record)
void visitRecordRecord(const RecordRecord &Record)
Visit a record record.
The JSON file list parser is used to communicate input to InstallAPI.
A type that provides access to a new line separated list of symbol names to ignore when extracting AP...
The base representation of an API record. Holds common symbol information.
Definition: API.h:156
This holds information associated with enums.
Definition: API.h:462
This holds information associated with global functions.
Definition: API.h:291
This holds information associated with global functions.
Definition: API.h:362
This holds information associated with macro definitions.
Definition: API.h:1079
This holds information associated with Objective-C categories.
Definition: API.h:1010
The base representation of an Objective-C container record.
Definition: API.h:902
This holds information associated with structs.
Definition: API.h:502
Common options to customize the visitor output.
bool Compact
Do not include unnecessary whitespaces to save space.
This represents a reference to another symbol that might come from external sources.
Definition: API.h:861
This holds information associated with typedefs.
Definition: API.h:1101