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