1 //===-- YAMLGenerator.cpp - ClangDoc YAML -----------------------*- 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 // Implementation of the YAML generator, converting decl info into YAML output.
9 //===----------------------------------------------------------------------===//
10 
11 #include "Generators.h"
12 #include "llvm/Support/YAMLTraits.h"
13 #include "llvm/Support/raw_ostream.h"
14 
15 using namespace clang::doc;
16 
17 LLVM_YAML_IS_SEQUENCE_VECTOR(FieldTypeInfo)
18 LLVM_YAML_IS_SEQUENCE_VECTOR(MemberTypeInfo)
19 LLVM_YAML_IS_SEQUENCE_VECTOR(Reference)
20 LLVM_YAML_IS_SEQUENCE_VECTOR(Location)
21 LLVM_YAML_IS_SEQUENCE_VECTOR(CommentInfo)
22 LLVM_YAML_IS_SEQUENCE_VECTOR(FunctionInfo)
23 LLVM_YAML_IS_SEQUENCE_VECTOR(EnumInfo)
24 LLVM_YAML_IS_SEQUENCE_VECTOR(BaseRecordInfo)
25 LLVM_YAML_IS_SEQUENCE_VECTOR(std::unique_ptr<CommentInfo>)
26 LLVM_YAML_IS_SEQUENCE_VECTOR(llvm::SmallString<16>)
27 
28 namespace llvm {
29 namespace yaml {
30 
31 // Enumerations to YAML output.
32 
33 template <> struct ScalarEnumerationTraits<clang::AccessSpecifier> {
enumerationllvm::yaml::ScalarEnumerationTraits34   static void enumeration(IO &IO, clang::AccessSpecifier &Value) {
35     IO.enumCase(Value, "Public", clang::AccessSpecifier::AS_public);
36     IO.enumCase(Value, "Protected", clang::AccessSpecifier::AS_protected);
37     IO.enumCase(Value, "Private", clang::AccessSpecifier::AS_private);
38     IO.enumCase(Value, "None", clang::AccessSpecifier::AS_none);
39   }
40 };
41 
42 template <> struct ScalarEnumerationTraits<clang::TagTypeKind> {
enumerationllvm::yaml::ScalarEnumerationTraits43   static void enumeration(IO &IO, clang::TagTypeKind &Value) {
44     IO.enumCase(Value, "Struct", clang::TagTypeKind::TTK_Struct);
45     IO.enumCase(Value, "Interface", clang::TagTypeKind::TTK_Interface);
46     IO.enumCase(Value, "Union", clang::TagTypeKind::TTK_Union);
47     IO.enumCase(Value, "Class", clang::TagTypeKind::TTK_Class);
48     IO.enumCase(Value, "Enum", clang::TagTypeKind::TTK_Enum);
49   }
50 };
51 
52 template <> struct ScalarEnumerationTraits<InfoType> {
enumerationllvm::yaml::ScalarEnumerationTraits53   static void enumeration(IO &IO, InfoType &Value) {
54     IO.enumCase(Value, "Namespace", InfoType::IT_namespace);
55     IO.enumCase(Value, "Record", InfoType::IT_record);
56     IO.enumCase(Value, "Function", InfoType::IT_function);
57     IO.enumCase(Value, "Enum", InfoType::IT_enum);
58     IO.enumCase(Value, "Default", InfoType::IT_default);
59   }
60 };
61 
62 // Scalars to YAML output.
63 template <unsigned U> struct ScalarTraits<SmallString<U>> {
64 
outputllvm::yaml::ScalarTraits65   static void output(const SmallString<U> &S, void *, llvm::raw_ostream &OS) {
66     for (const auto &C : S)
67       OS << C;
68   }
69 
inputllvm::yaml::ScalarTraits70   static StringRef input(StringRef Scalar, void *, SmallString<U> &Value) {
71     Value.assign(Scalar.begin(), Scalar.end());
72     return StringRef();
73   }
74 
mustQuotellvm::yaml::ScalarTraits75   static QuotingType mustQuote(StringRef) { return QuotingType::Single; }
76 };
77 
78 template <> struct ScalarTraits<std::array<unsigned char, 20>> {
79 
outputllvm::yaml::ScalarTraits80   static void output(const std::array<unsigned char, 20> &S, void *,
81                      llvm::raw_ostream &OS) {
82     OS << toHex(toStringRef(S));
83   }
84 
inputllvm::yaml::ScalarTraits85   static StringRef input(StringRef Scalar, void *,
86                          std::array<unsigned char, 20> &Value) {
87     if (Scalar.size() != 40)
88       return "Error: Incorrect scalar size for USR.";
89     Value = StringToSymbol(Scalar);
90     return StringRef();
91   }
92 
StringToSymbolllvm::yaml::ScalarTraits93   static SymbolID StringToSymbol(llvm::StringRef Value) {
94     SymbolID USR;
95     std::string HexString = fromHex(Value);
96     std::copy(HexString.begin(), HexString.end(), USR.begin());
97     return SymbolID(USR);
98   }
99 
mustQuotellvm::yaml::ScalarTraits100   static QuotingType mustQuote(StringRef) { return QuotingType::Single; }
101 };
102 
103 // Helper functions to map infos to YAML.
104 
TypeInfoMapping(IO & IO,TypeInfo & I)105 static void TypeInfoMapping(IO &IO, TypeInfo &I) {
106   IO.mapOptional("Type", I.Type, Reference());
107 }
108 
FieldTypeInfoMapping(IO & IO,FieldTypeInfo & I)109 static void FieldTypeInfoMapping(IO &IO, FieldTypeInfo &I) {
110   TypeInfoMapping(IO, I);
111   IO.mapOptional("Name", I.Name, SmallString<16>());
112 }
113 
InfoMapping(IO & IO,Info & I)114 static void InfoMapping(IO &IO, Info &I) {
115   IO.mapRequired("USR", I.USR);
116   IO.mapOptional("Name", I.Name, SmallString<16>());
117   IO.mapOptional("Path", I.Path, SmallString<128>());
118   IO.mapOptional("Namespace", I.Namespace, llvm::SmallVector<Reference, 4>());
119   IO.mapOptional("Description", I.Description);
120 }
121 
SymbolInfoMapping(IO & IO,SymbolInfo & I)122 static void SymbolInfoMapping(IO &IO, SymbolInfo &I) {
123   InfoMapping(IO, I);
124   IO.mapOptional("DefLocation", I.DefLoc, Optional<Location>());
125   IO.mapOptional("Location", I.Loc, llvm::SmallVector<Location, 2>());
126 }
127 
RecordInfoMapping(IO & IO,RecordInfo & I)128 static void RecordInfoMapping(IO &IO, RecordInfo &I) {
129   SymbolInfoMapping(IO, I);
130   IO.mapOptional("TagType", I.TagType, clang::TagTypeKind::TTK_Struct);
131   IO.mapOptional("Members", I.Members);
132   IO.mapOptional("Bases", I.Bases);
133   IO.mapOptional("Parents", I.Parents, llvm::SmallVector<Reference, 4>());
134   IO.mapOptional("VirtualParents", I.VirtualParents,
135                  llvm::SmallVector<Reference, 4>());
136   IO.mapOptional("ChildRecords", I.ChildRecords, std::vector<Reference>());
137   IO.mapOptional("ChildFunctions", I.ChildFunctions);
138   IO.mapOptional("ChildEnums", I.ChildEnums);
139 }
140 
CommentInfoMapping(IO & IO,CommentInfo & I)141 static void CommentInfoMapping(IO &IO, CommentInfo &I) {
142   IO.mapOptional("Kind", I.Kind, SmallString<16>());
143   IO.mapOptional("Text", I.Text, SmallString<64>());
144   IO.mapOptional("Name", I.Name, SmallString<16>());
145   IO.mapOptional("Direction", I.Direction, SmallString<8>());
146   IO.mapOptional("ParamName", I.ParamName, SmallString<16>());
147   IO.mapOptional("CloseName", I.CloseName, SmallString<16>());
148   IO.mapOptional("SelfClosing", I.SelfClosing, false);
149   IO.mapOptional("Explicit", I.Explicit, false);
150   IO.mapOptional("Args", I.Args, llvm::SmallVector<SmallString<16>, 4>());
151   IO.mapOptional("AttrKeys", I.AttrKeys,
152                  llvm::SmallVector<SmallString<16>, 4>());
153   IO.mapOptional("AttrValues", I.AttrValues,
154                  llvm::SmallVector<SmallString<16>, 4>());
155   IO.mapOptional("Children", I.Children);
156 }
157 
158 // Template specialization to YAML traits for Infos.
159 
160 template <> struct MappingTraits<Location> {
mappingllvm::yaml::MappingTraits161   static void mapping(IO &IO, Location &Loc) {
162     IO.mapOptional("LineNumber", Loc.LineNumber, 0);
163     IO.mapOptional("Filename", Loc.Filename, SmallString<32>());
164   }
165 };
166 
167 template <> struct MappingTraits<Reference> {
mappingllvm::yaml::MappingTraits168   static void mapping(IO &IO, Reference &Ref) {
169     IO.mapOptional("Type", Ref.RefType, InfoType::IT_default);
170     IO.mapOptional("Name", Ref.Name, SmallString<16>());
171     IO.mapOptional("USR", Ref.USR, SymbolID());
172     IO.mapOptional("Path", Ref.Path, SmallString<128>());
173     IO.mapOptional("IsInGlobalNamespace", Ref.IsInGlobalNamespace, false);
174   }
175 };
176 
177 template <> struct MappingTraits<TypeInfo> {
mappingllvm::yaml::MappingTraits178   static void mapping(IO &IO, TypeInfo &I) { TypeInfoMapping(IO, I); }
179 };
180 
181 template <> struct MappingTraits<FieldTypeInfo> {
mappingllvm::yaml::MappingTraits182   static void mapping(IO &IO, FieldTypeInfo &I) {
183     TypeInfoMapping(IO, I);
184     IO.mapOptional("Name", I.Name, SmallString<16>());
185   }
186 };
187 
188 template <> struct MappingTraits<MemberTypeInfo> {
mappingllvm::yaml::MappingTraits189   static void mapping(IO &IO, MemberTypeInfo &I) {
190     FieldTypeInfoMapping(IO, I);
191     // clang::AccessSpecifier::AS_none is used as the default here because it's
192     // the AS that shouldn't be part of the output. Even though AS_public is the
193     // default in the struct, it should be displayed in the YAML output.
194     IO.mapOptional("Access", I.Access, clang::AccessSpecifier::AS_none);
195   }
196 };
197 
198 template <> struct MappingTraits<NamespaceInfo> {
mappingllvm::yaml::MappingTraits199   static void mapping(IO &IO, NamespaceInfo &I) {
200     InfoMapping(IO, I);
201     IO.mapOptional("ChildNamespaces", I.ChildNamespaces,
202                    std::vector<Reference>());
203     IO.mapOptional("ChildRecords", I.ChildRecords, std::vector<Reference>());
204     IO.mapOptional("ChildFunctions", I.ChildFunctions);
205     IO.mapOptional("ChildEnums", I.ChildEnums);
206   }
207 };
208 
209 template <> struct MappingTraits<RecordInfo> {
mappingllvm::yaml::MappingTraits210   static void mapping(IO &IO, RecordInfo &I) { RecordInfoMapping(IO, I); }
211 };
212 
213 template <> struct MappingTraits<BaseRecordInfo> {
mappingllvm::yaml::MappingTraits214   static void mapping(IO &IO, BaseRecordInfo &I) {
215     RecordInfoMapping(IO, I);
216     IO.mapOptional("IsVirtual", I.IsVirtual, false);
217     // clang::AccessSpecifier::AS_none is used as the default here because it's
218     // the AS that shouldn't be part of the output. Even though AS_public is the
219     // default in the struct, it should be displayed in the YAML output.
220     IO.mapOptional("Access", I.Access, clang::AccessSpecifier::AS_none);
221     IO.mapOptional("IsParent", I.IsParent, false);
222   }
223 };
224 
225 template <> struct MappingTraits<EnumInfo> {
mappingllvm::yaml::MappingTraits226   static void mapping(IO &IO, EnumInfo &I) {
227     SymbolInfoMapping(IO, I);
228     IO.mapOptional("Scoped", I.Scoped, false);
229     IO.mapOptional("Members", I.Members);
230   }
231 };
232 
233 template <> struct MappingTraits<FunctionInfo> {
mappingllvm::yaml::MappingTraits234   static void mapping(IO &IO, FunctionInfo &I) {
235     SymbolInfoMapping(IO, I);
236     IO.mapOptional("IsMethod", I.IsMethod, false);
237     IO.mapOptional("Parent", I.Parent, Reference());
238     IO.mapOptional("Params", I.Params);
239     IO.mapOptional("ReturnType", I.ReturnType);
240     // clang::AccessSpecifier::AS_none is used as the default here because it's
241     // the AS that shouldn't be part of the output. Even though AS_public is the
242     // default in the struct, it should be displayed in the YAML output.
243     IO.mapOptional("Access", I.Access, clang::AccessSpecifier::AS_none);
244   }
245 };
246 
247 template <> struct MappingTraits<CommentInfo> {
mappingllvm::yaml::MappingTraits248   static void mapping(IO &IO, CommentInfo &I) { CommentInfoMapping(IO, I); }
249 };
250 
251 template <> struct MappingTraits<std::unique_ptr<CommentInfo>> {
mappingllvm::yaml::MappingTraits252   static void mapping(IO &IO, std::unique_ptr<CommentInfo> &I) {
253     if (I)
254       CommentInfoMapping(IO, *I);
255   }
256 };
257 
258 } // end namespace yaml
259 } // end namespace llvm
260 
261 namespace clang {
262 namespace doc {
263 
264 /// Generator for YAML documentation.
265 class YAMLGenerator : public Generator {
266 public:
267   static const char *Format;
268 
269   llvm::Error generateDocForInfo(Info *I, llvm::raw_ostream &OS,
270                                  const ClangDocContext &CDCtx) override;
271 };
272 
273 const char *YAMLGenerator::Format = "yaml";
274 
generateDocForInfo(Info * I,llvm::raw_ostream & OS,const ClangDocContext & CDCtx)275 llvm::Error YAMLGenerator::generateDocForInfo(Info *I, llvm::raw_ostream &OS,
276                                               const ClangDocContext &CDCtx) {
277   llvm::yaml::Output InfoYAML(OS);
278   switch (I->IT) {
279   case InfoType::IT_namespace:
280     InfoYAML << *static_cast<clang::doc::NamespaceInfo *>(I);
281     break;
282   case InfoType::IT_record:
283     InfoYAML << *static_cast<clang::doc::RecordInfo *>(I);
284     break;
285   case InfoType::IT_enum:
286     InfoYAML << *static_cast<clang::doc::EnumInfo *>(I);
287     break;
288   case InfoType::IT_function:
289     InfoYAML << *static_cast<clang::doc::FunctionInfo *>(I);
290     break;
291   case InfoType::IT_default:
292     return llvm::createStringError(llvm::inconvertibleErrorCode(),
293                                    "unexpected InfoType");
294   }
295   return llvm::Error::success();
296 }
297 
298 static GeneratorRegistry::Add<YAMLGenerator> YAML(YAMLGenerator::Format,
299                                                   "Generator for YAML output.");
300 
301 // This anchor is used to force the linker to link in the generated object file
302 // and thus register the generator.
303 volatile int YAMLGeneratorAnchorSource = 0;
304 
305 } // namespace doc
306 } // namespace clang
307