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:
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.
175
177
179
181
184
187
189
191
193
196
198
200
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.
229
230 /// Serialize a single 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.
llvm::MachO::Target Target
Definition: MachO.h:44
llvm::MachO::Record Record
Definition: MachO.h:28
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