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