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};
35struct DocumentedGroup : Documentation {
36  Record *Group;
37};
38
39// Reorganize the records into a suitable form for emitting documentation.
40Documentation 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.
141std::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
150const 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.
154unsigned 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
164bool 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
171bool 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
179std::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
189StringRef 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
196bool 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
205void 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.
213std::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
229void 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
243void 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
283bool 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
293template <typename Fn>
294void 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
303void 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
352void emitDocumentation(int Depth, const Documentation &Doc,
353                       const Record *DocInfo, raw_ostream &OS);
354
355void 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
373void 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
383void 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