1//===- ClangOptionDocEmitter.cpp - Documentation for command line flags ---===//
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// FIXME: Once this has stabilized, consider moving it to LLVM.
8//
9//===----------------------------------------------------------------------===//
10
11#include "TableGenBackends.h"
12#include "llvm/TableGen/Error.h"
13#include "llvm/ADT/STLExtras.h"
14#include "llvm/ADT/SmallString.h"
15#include "llvm/ADT/StringSwitch.h"
16#include "llvm/ADT/Twine.h"
17#include "llvm/TableGen/Record.h"
18#include "llvm/TableGen/TableGenBackend.h"
19#include <cctype>
20#include <cstring>
21#include <map>
22
23using namespace llvm;
24
25namespace {
26struct DocumentedOption {
27 Record *Option;
28 std::vector<Record*> Aliases;
29};
30struct DocumentedGroup;
31struct Documentation {
32 std::vector<DocumentedGroup> Groups;
33 std::vector<DocumentedOption> Options;
34
35 bool empty() {
36 return Groups.empty() && Options.empty();
37 }
38};
39struct DocumentedGroup : Documentation {
40 Record *Group;
41};
42
43static bool hasFlag(const Record *Option, StringRef OptionFlag,
44 StringRef FlagsField) {
45 for (const Record *Flag : Option->getValueAsListOfDefs(FieldName: FlagsField))
46 if (Flag->getName() == OptionFlag)
47 return true;
48 if (const DefInit *DI = dyn_cast<DefInit>(Val: Option->getValueInit(FieldName: "Group")))
49 for (const Record *Flag : DI->getDef()->getValueAsListOfDefs(FieldName: FlagsField))
50 if (Flag->getName() == OptionFlag)
51 return true;
52 return false;
53}
54
55static bool isOptionVisible(const Record *Option, const Record *DocInfo) {
56 for (StringRef IgnoredFlag : DocInfo->getValueAsListOfStrings(FieldName: "IgnoreFlags"))
57 if (hasFlag(Option, OptionFlag: IgnoredFlag, FlagsField: "Flags"))
58 return false;
59 for (StringRef Mask : DocInfo->getValueAsListOfStrings(FieldName: "VisibilityMask"))
60 if (hasFlag(Option, OptionFlag: Mask, FlagsField: "Visibility"))
61 return true;
62 return false;
63}
64
65// Reorganize the records into a suitable form for emitting documentation.
66Documentation extractDocumentation(RecordKeeper &Records,
67 const Record *DocInfo) {
68 Documentation Result;
69
70 // Build the tree of groups. The root in the tree is the fake option group
71 // (Record*)nullptr, which contains all top-level groups and options.
72 std::map<Record*, std::vector<Record*> > OptionsInGroup;
73 std::map<Record*, std::vector<Record*> > GroupsInGroup;
74 std::map<Record*, std::vector<Record*> > Aliases;
75
76 std::map<std::string, Record*> OptionsByName;
77 for (Record *R : Records.getAllDerivedDefinitions(ClassName: "Option"))
78 OptionsByName[std::string(R->getValueAsString(FieldName: "Name"))] = R;
79
80 auto Flatten = [](Record *R) {
81 return R->getValue(Name: "DocFlatten") && R->getValueAsBit(FieldName: "DocFlatten");
82 };
83
84 auto SkipFlattened = [&](Record *R) -> Record* {
85 while (R && Flatten(R)) {
86 auto *G = dyn_cast<DefInit>(Val: R->getValueInit(FieldName: "Group"));
87 if (!G)
88 return nullptr;
89 R = G->getDef();
90 }
91 return R;
92 };
93
94 for (Record *R : Records.getAllDerivedDefinitions(ClassName: "OptionGroup")) {
95 if (Flatten(R))
96 continue;
97
98 Record *Group = nullptr;
99 if (auto *G = dyn_cast<DefInit>(Val: R->getValueInit(FieldName: "Group")))
100 Group = SkipFlattened(G->getDef());
101 GroupsInGroup[Group].push_back(x: R);
102 }
103
104 for (Record *R : Records.getAllDerivedDefinitions(ClassName: "Option")) {
105 if (auto *A = dyn_cast<DefInit>(Val: R->getValueInit(FieldName: "Alias"))) {
106 Aliases[A->getDef()].push_back(x: R);
107 continue;
108 }
109
110 // Pretend no-X and Xno-Y options are aliases of X and XY.
111 std::string Name = std::string(R->getValueAsString(FieldName: "Name"));
112 if (Name.size() >= 4) {
113 if (Name.substr(pos: 0, n: 3) == "no-" && OptionsByName[Name.substr(pos: 3)]) {
114 Aliases[OptionsByName[Name.substr(pos: 3)]].push_back(x: R);
115 continue;
116 }
117 if (Name.substr(pos: 1, n: 3) == "no-" && OptionsByName[Name[0] + Name.substr(pos: 4)]) {
118 Aliases[OptionsByName[Name[0] + Name.substr(pos: 4)]].push_back(x: R);
119 continue;
120 }
121 }
122
123 Record *Group = nullptr;
124 if (auto *G = dyn_cast<DefInit>(Val: R->getValueInit(FieldName: "Group")))
125 Group = SkipFlattened(G->getDef());
126 OptionsInGroup[Group].push_back(x: R);
127 }
128
129 auto CompareByName = [](Record *A, Record *B) {
130 return A->getValueAsString(FieldName: "Name") < B->getValueAsString(FieldName: "Name");
131 };
132
133 auto CompareByLocation = [](Record *A, Record *B) {
134 return A->getLoc()[0].getPointer() < B->getLoc()[0].getPointer();
135 };
136
137 auto DocumentationForOption = [&](Record *R) -> DocumentedOption {
138 auto &A = Aliases[R];
139 llvm::sort(C&: A, Comp: CompareByName);
140 return {.Option: R, .Aliases: std::move(A)};
141 };
142
143 std::function<Documentation(Record *)> DocumentationForGroup =
144 [&](Record *R) -> Documentation {
145 Documentation D;
146
147 auto &Groups = GroupsInGroup[R];
148 llvm::sort(C&: Groups, Comp: CompareByLocation);
149 for (Record *G : Groups) {
150 D.Groups.emplace_back();
151 D.Groups.back().Group = G;
152 Documentation &Base = D.Groups.back();
153 Base = DocumentationForGroup(G);
154 if (Base.empty())
155 D.Groups.pop_back();
156 }
157
158 auto &Options = OptionsInGroup[R];
159 llvm::sort(C&: Options, Comp: CompareByName);
160 for (Record *O : Options)
161 if (isOptionVisible(Option: O, DocInfo))
162 D.Options.push_back(x: DocumentationForOption(O));
163
164 return D;
165 };
166
167 return DocumentationForGroup(nullptr);
168}
169
170// Get the first and successive separators to use for an OptionKind.
171std::pair<StringRef,StringRef> getSeparatorsForKind(const Record *OptionKind) {
172 return StringSwitch<std::pair<StringRef, StringRef>>(OptionKind->getName())
173 .Cases(S0: "KIND_JOINED", S1: "KIND_JOINED_OR_SEPARATE",
174 S2: "KIND_JOINED_AND_SEPARATE",
175 S3: "KIND_REMAINING_ARGS_JOINED", Value: {"", " "})
176 .Case(S: "KIND_COMMAJOINED", Value: {"", ","})
177 .Default(Value: {" ", " "});
178}
179
180const unsigned UnlimitedArgs = unsigned(-1);
181
182// Get the number of arguments expected for an option, or -1 if any number of
183// arguments are accepted.
184unsigned getNumArgsForKind(Record *OptionKind, const Record *Option) {
185 return StringSwitch<unsigned>(OptionKind->getName())
186 .Cases(S0: "KIND_JOINED", S1: "KIND_JOINED_OR_SEPARATE", S2: "KIND_SEPARATE", Value: 1)
187 .Cases(S0: "KIND_REMAINING_ARGS", S1: "KIND_REMAINING_ARGS_JOINED",
188 S2: "KIND_COMMAJOINED", Value: UnlimitedArgs)
189 .Case(S: "KIND_JOINED_AND_SEPARATE", Value: 2)
190 .Case(S: "KIND_MULTIARG", Value: Option->getValueAsInt(FieldName: "NumArgs"))
191 .Default(Value: 0);
192}
193
194std::string escapeRST(StringRef Str) {
195 std::string Out;
196 for (auto K : Str) {
197 if (StringRef("`*|[]\\").count(C: K))
198 Out.push_back(c: '\\');
199 Out.push_back(c: K);
200 }
201 return Out;
202}
203
204StringRef getSphinxOptionID(StringRef OptionName) {
205 for (auto I = OptionName.begin(), E = OptionName.end(); I != E; ++I)
206 if (!isalnum(*I) && *I != '-')
207 return OptionName.substr(Start: 0, N: I - OptionName.begin());
208 return OptionName;
209}
210
211bool canSphinxCopeWithOption(const Record *Option) {
212 // HACK: Work arond sphinx's inability to cope with punctuation-only options
213 // such as /? by suppressing them from the option list.
214 for (char C : Option->getValueAsString(FieldName: "Name"))
215 if (isalnum(C))
216 return true;
217 return false;
218}
219
220void emitHeading(int Depth, std::string Heading, raw_ostream &OS) {
221 assert(Depth < 8 && "groups nested too deeply");
222 OS << Heading << '\n'
223 << std::string(Heading.size(), "=~-_'+<>"[Depth]) << "\n";
224}
225
226/// Get the value of field \p Primary, if possible. If \p Primary does not
227/// exist, get the value of \p Fallback and escape it for rST emission.
228std::string getRSTStringWithTextFallback(const Record *R, StringRef Primary,
229 StringRef Fallback) {
230 for (auto Field : {Primary, Fallback}) {
231 if (auto *V = R->getValue(Name: Field)) {
232 StringRef Value;
233 if (auto *SV = dyn_cast_or_null<StringInit>(Val: V->getValue()))
234 Value = SV->getValue();
235 if (!Value.empty())
236 return Field == Primary ? Value.str() : escapeRST(Str: Value);
237 }
238 }
239 return std::string(StringRef());
240}
241
242void emitOptionWithArgs(StringRef Prefix, const Record *Option,
243 ArrayRef<StringRef> Args, raw_ostream &OS) {
244 OS << Prefix << escapeRST(Str: Option->getValueAsString(FieldName: "Name"));
245
246 std::pair<StringRef, StringRef> Separators =
247 getSeparatorsForKind(OptionKind: Option->getValueAsDef(FieldName: "Kind"));
248
249 StringRef Separator = Separators.first;
250 for (auto Arg : Args) {
251 OS << Separator << escapeRST(Str: Arg);
252 Separator = Separators.second;
253 }
254}
255
256constexpr StringLiteral DefaultMetaVarName = "<arg>";
257
258void emitOptionName(StringRef Prefix, const Record *Option, raw_ostream &OS) {
259 // Find the arguments to list after the option.
260 unsigned NumArgs = getNumArgsForKind(OptionKind: Option->getValueAsDef(FieldName: "Kind"), Option);
261 bool HasMetaVarName = !Option->isValueUnset(FieldName: "MetaVarName");
262
263 std::vector<std::string> Args;
264 if (HasMetaVarName)
265 Args.push_back(x: std::string(Option->getValueAsString(FieldName: "MetaVarName")));
266 else if (NumArgs == 1)
267 Args.push_back(x: DefaultMetaVarName.str());
268
269 // Fill up arguments if this option didn't provide a meta var name or it
270 // supports an unlimited number of arguments. We can't see how many arguments
271 // already are in a meta var name, so assume it has right number. This is
272 // needed for JoinedAndSeparate options so that there arent't too many
273 // arguments.
274 if (!HasMetaVarName || NumArgs == UnlimitedArgs) {
275 while (Args.size() < NumArgs) {
276 Args.push_back(x: ("<arg" + Twine(Args.size() + 1) + ">").str());
277 // Use '--args <arg1> <arg2>...' if any number of args are allowed.
278 if (Args.size() == 2 && NumArgs == UnlimitedArgs) {
279 Args.back() += "...";
280 break;
281 }
282 }
283 }
284
285 emitOptionWithArgs(Prefix, Option, Args: std::vector<StringRef>(Args.begin(), Args.end()), OS);
286
287 auto AliasArgs = Option->getValueAsListOfStrings(FieldName: "AliasArgs");
288 if (!AliasArgs.empty()) {
289 Record *Alias = Option->getValueAsDef(FieldName: "Alias");
290 OS << " (equivalent to ";
291 emitOptionWithArgs(
292 Prefix: Alias->getValueAsListOfStrings(FieldName: "Prefixes").front(), Option: Alias,
293 Args: AliasArgs, OS);
294 OS << ")";
295 }
296}
297
298bool emitOptionNames(const Record *Option, raw_ostream &OS, bool EmittedAny) {
299 for (auto &Prefix : Option->getValueAsListOfStrings(FieldName: "Prefixes")) {
300 if (EmittedAny)
301 OS << ", ";
302 emitOptionName(Prefix, Option, OS);
303 EmittedAny = true;
304 }
305 return EmittedAny;
306}
307
308template <typename Fn>
309void forEachOptionName(const DocumentedOption &Option, const Record *DocInfo,
310 Fn F) {
311 F(Option.Option);
312
313 for (auto *Alias : Option.Aliases)
314 if (isOptionVisible(Option: Alias, DocInfo) &&
315 canSphinxCopeWithOption(Option: Option.Option))
316 F(Alias);
317}
318
319void emitOption(const DocumentedOption &Option, const Record *DocInfo,
320 raw_ostream &OS) {
321 if (Option.Option->getValueAsDef(FieldName: "Kind")->getName() == "KIND_UNKNOWN" ||
322 Option.Option->getValueAsDef(FieldName: "Kind")->getName() == "KIND_INPUT")
323 return;
324 if (!canSphinxCopeWithOption(Option: Option.Option))
325 return;
326
327 // HACK: Emit a different program name with each option to work around
328 // sphinx's inability to cope with options that differ only by punctuation
329 // (eg -ObjC vs -ObjC++, -G vs -G=).
330 std::vector<std::string> SphinxOptionIDs;
331 forEachOptionName(Option, DocInfo, F: [&](const Record *Option) {
332 for (auto &Prefix : Option->getValueAsListOfStrings(FieldName: "Prefixes"))
333 SphinxOptionIDs.push_back(x: std::string(getSphinxOptionID(
334 OptionName: (Prefix + Option->getValueAsString(FieldName: "Name")).str())));
335 });
336 assert(!SphinxOptionIDs.empty() && "no flags for option");
337 static std::map<std::string, int> NextSuffix;
338 int SphinxWorkaroundSuffix = NextSuffix[*std::max_element(
339 first: SphinxOptionIDs.begin(), last: SphinxOptionIDs.end(),
340 comp: [&](const std::string &A, const std::string &B) {
341 return NextSuffix[A] < NextSuffix[B];
342 })];
343 for (auto &S : SphinxOptionIDs)
344 NextSuffix[S] = SphinxWorkaroundSuffix + 1;
345
346 std::string Program = DocInfo->getValueAsString(FieldName: "Program").lower();
347 if (SphinxWorkaroundSuffix)
348 OS << ".. program:: " << Program << SphinxWorkaroundSuffix << "\n";
349
350 // Emit the names of the option.
351 OS << ".. option:: ";
352 bool EmittedAny = false;
353 forEachOptionName(Option, DocInfo, F: [&](const Record *Option) {
354 EmittedAny = emitOptionNames(Option, OS, EmittedAny);
355 });
356 if (SphinxWorkaroundSuffix)
357 OS << "\n.. program:: " << Program;
358 OS << "\n\n";
359
360 // Emit the description, if we have one.
361 const Record *R = Option.Option;
362 std::string Description;
363
364 // Prefer a program specific help string.
365 // This is a list of (visibilities, string) pairs.
366 std::vector<Record *> VisibilitiesHelp =
367 R->getValueAsListOfDefs(FieldName: "HelpTextsForVariants");
368 for (Record *VisibilityHelp : VisibilitiesHelp) {
369 // This is a list of visibilities.
370 ArrayRef<Init *> Visibilities =
371 VisibilityHelp->getValueAsListInit(FieldName: "Visibilities")->getValues();
372
373 // See if any of the program's visibilities are in the list.
374 for (StringRef DocInfoMask :
375 DocInfo->getValueAsListOfStrings(FieldName: "VisibilityMask")) {
376 for (Init *Visibility : Visibilities) {
377 if (Visibility->getAsUnquotedString() == DocInfoMask) {
378 // Use the first one we find.
379 Description = escapeRST(Str: VisibilityHelp->getValueAsString(FieldName: "Text"));
380 break;
381 }
382 }
383 if (!Description.empty())
384 break;
385 }
386
387 if (!Description.empty())
388 break;
389 }
390
391 // If there's not a program specific string, use the default one.
392 if (Description.empty())
393 Description = getRSTStringWithTextFallback(R, Primary: "DocBrief", Fallback: "HelpText");
394
395 if (!isa<UnsetInit>(Val: R->getValueInit(FieldName: "Values"))) {
396 if (!Description.empty() && Description.back() != '.')
397 Description.push_back(c: '.');
398
399 StringRef MetaVarName;
400 if (!isa<UnsetInit>(Val: R->getValueInit(FieldName: "MetaVarName")))
401 MetaVarName = R->getValueAsString(FieldName: "MetaVarName");
402 else
403 MetaVarName = DefaultMetaVarName;
404
405 SmallVector<StringRef> Values;
406 SplitString(Source: R->getValueAsString(FieldName: "Values"), OutFragments&: Values, Delimiters: ",");
407 Description += (" " + MetaVarName + " must be '").str();
408 if (Values.size() > 1) {
409 Description += join(Begin: Values.begin(), End: Values.end() - 1, Separator: "', '");
410 Description += "' or '";
411 }
412 Description += (Values.back() + "'.").str();
413 }
414
415 if (!Description.empty())
416 OS << Description << "\n\n";
417}
418
419void emitDocumentation(int Depth, const Documentation &Doc,
420 const Record *DocInfo, raw_ostream &OS);
421
422void emitGroup(int Depth, const DocumentedGroup &Group, const Record *DocInfo,
423 raw_ostream &OS) {
424 emitHeading(Depth,
425 Heading: getRSTStringWithTextFallback(R: Group.Group, Primary: "DocName", Fallback: "Name"), OS);
426
427 // Emit the description, if we have one.
428 std::string Description =
429 getRSTStringWithTextFallback(R: Group.Group, Primary: "DocBrief", Fallback: "HelpText");
430 if (!Description.empty())
431 OS << Description << "\n\n";
432
433 // Emit contained options and groups.
434 emitDocumentation(Depth: Depth + 1, Doc: Group, DocInfo, OS);
435}
436
437void emitDocumentation(int Depth, const Documentation &Doc,
438 const Record *DocInfo, raw_ostream &OS) {
439 for (auto &O : Doc.Options)
440 emitOption(Option: O, DocInfo, OS);
441 for (auto &G : Doc.Groups)
442 emitGroup(Depth, Group: G, DocInfo, OS);
443}
444
445} // namespace
446
447void clang::EmitClangOptDocs(RecordKeeper &Records, raw_ostream &OS) {
448 const Record *DocInfo = Records.getDef(Name: "GlobalDocumentation");
449 if (!DocInfo) {
450 PrintFatalError(Msg: "The GlobalDocumentation top-level definition is missing, "
451 "no documentation will be generated.");
452 return;
453 }
454 OS << DocInfo->getValueAsString(FieldName: "Intro") << "\n";
455 OS << ".. program:: " << DocInfo->getValueAsString(FieldName: "Program").lower() << "\n";
456
457 emitDocumentation(Depth: 0, Doc: extractDocumentation(Records, DocInfo), DocInfo, OS);
458}
459

source code of clang/utils/TableGen/ClangOptionDocEmitter.cpp