clang/utils/TableGen/ClangOptionDocEmitter.cpp

   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[std::string(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 = std::string(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 isIncluded(const Record *OptionOrGroup, const Record *DocInfo) {
 172   assert(DocInfo->getValue("IncludedFlags") && "Missing includeFlags");
 173   for (StringRef Inclusion : DocInfo->getValueAsListOfStrings("IncludedFlags"))
 174     if (hasFlag(OptionOrGroup, Inclusion))
 175       return true;
 176   return false;
 177 }
 178
 179 bool isGroupIncluded(const DocumentedGroup &Group, const Record *DocInfo) {
 180   if (isIncluded(Group.Group, DocInfo))
 181     return true;
 182   for (auto &O : Group.Options)
 183     if (isIncluded(O.Option, DocInfo))
 184       return true;
 185   for (auto &G : Group.Groups) {
 186     if (isIncluded(G.Group, DocInfo))
 187       return true;
 188     if (isGroupIncluded(G, DocInfo))
 189       return true;
 190   }
 191   return false;
 192 }
 193
 194 bool isExcluded(const Record *OptionOrGroup, const Record *DocInfo) {
 195   // FIXME: Provide a flag to specify the set of exclusions.
 196   for (StringRef Exclusion : DocInfo->getValueAsListOfStrings("ExcludedFlags"))
 197     if (hasFlag(OptionOrGroup, Exclusion))
 198       return true;
 199   return false;
 200 }
 201
 202 std::string escapeRST(StringRef Str) {
 203   std::string Out;
 204   for (auto K : Str) {
 205     if (StringRef("`*|_[]\\").count(K))
 206       Out.push_back('\\');
 207     Out.push_back(K);
 208   }
 209   return Out;
 210 }
 211
 212 StringRef getSphinxOptionID(StringRef OptionName) {
 213   for (auto I = OptionName.begin(), E = OptionName.end(); I != E; ++I)
 214     if (!isalnum(*I) && *I != '-')
 215       return OptionName.substr(0, I - OptionName.begin());
 216   return OptionName;
 217 }
 218
 219 bool canSphinxCopeWithOption(const Record *Option) {
 220   // HACK: Work arond sphinx's inability to cope with punctuation-only options
 221   // such as /? by suppressing them from the option list.
 222   for (char C : Option->getValueAsString("Name"))
 223     if (isalnum(C))
 224       return true;
 225   return false;
 226 }
 227
 228 void emitHeading(int Depth, std::string Heading, raw_ostream &OS) {
 229   assert(Depth < 8 && "groups nested too deeply");
 230   OS << Heading << '\n'
 231      << std::string(Heading.size(), "=~-_'+<>"[Depth]) << "\n";
 232 }
 233
 234 /// Get the value of field \p Primary, if possible. If \p Primary does not
 235 /// exist, get the value of \p Fallback and escape it for rST emission.
 236 std::string getRSTStringWithTextFallback(const Record *R, StringRef Primary,
 237                                          StringRef Fallback) {
 238   for (auto Field : {Primary, Fallback}) {
 239     if (auto *V = R->getValue(Field)) {
 240       StringRef Value;
 241       if (auto *SV = dyn_cast_or_null<StringInit>(V->getValue()))
 242         Value = SV->getValue();
 243       if (!Value.empty())
 244         return Field == Primary ? Value.str() : escapeRST(Value);
 245     }
 246   }
 247   return std::string(StringRef());
 248 }
 249
 250 void emitOptionWithArgs(StringRef Prefix, const Record *Option,
 251                         ArrayRef<StringRef> Args, raw_ostream &OS) {
 252   OS << Prefix << escapeRST(Option->getValueAsString("Name"));
 253
 254   std::pair<StringRef, StringRef> Separators =
 255       getSeparatorsForKind(Option->getValueAsDef("Kind"));
 256
 257   StringRef Separator = Separators.first;
 258   for (auto Arg : Args) {
 259     OS << Separator << escapeRST(Arg);
 260     Separator = Separators.second;
 261   }
 262 }
 263
 264 constexpr StringLiteral DefaultMetaVarName = "<arg>";
 265
 266 void emitOptionName(StringRef Prefix, const Record *Option, raw_ostream &OS) {
 267   // Find the arguments to list after the option.
 268   unsigned NumArgs = getNumArgsForKind(Option->getValueAsDef("Kind"), Option);
 269   bool HasMetaVarName = !Option->isValueUnset("MetaVarName");
 270
 271   std::vector<std::string> Args;
 272   if (HasMetaVarName)
 273     Args.push_back(std::string(Option->getValueAsString("MetaVarName")));
 274   else if (NumArgs == 1)
 275     Args.push_back(DefaultMetaVarName.str());
 276
 277   // Fill up arguments if this option didn't provide a meta var name or it
 278   // supports an unlimited number of arguments. We can't see how many arguments
 279   // already are in a meta var name, so assume it has right number. This is
 280   // needed for JoinedAndSeparate options so that there arent't too many
 281   // arguments.
 282   if (!HasMetaVarName || NumArgs == UnlimitedArgs) {
 283     while (Args.size() < NumArgs) {
 284       Args.push_back(("<arg" + Twine(Args.size() + 1) + ">").str());
 285       // Use '--args <arg1> <arg2>...' if any number of args are allowed.
 286       if (Args.size() == 2 && NumArgs == UnlimitedArgs) {
 287         Args.back() += "...";
 288         break;
 289       }
 290     }
 291   }
 292
 293   emitOptionWithArgs(Prefix, Option, std::vector<StringRef>(Args.begin(), Args.end()), OS);
 294
 295   auto AliasArgs = Option->getValueAsListOfStrings("AliasArgs");
 296   if (!AliasArgs.empty()) {
 297     Record *Alias = Option->getValueAsDef("Alias");
 298     OS << " (equivalent to ";
 299     emitOptionWithArgs(
 300         Alias->getValueAsListOfStrings("Prefixes").front(), Alias,
 301         AliasArgs, OS);
 302     OS << ")";
 303   }
 304 }
 305
 306 bool emitOptionNames(const Record *Option, raw_ostream &OS, bool EmittedAny) {
 307   for (auto &Prefix : Option->getValueAsListOfStrings("Prefixes")) {
 308     if (EmittedAny)
 309       OS << ", ";
 310     emitOptionName(Prefix, Option, OS);
 311     EmittedAny = true;
 312   }
 313   return EmittedAny;
 314 }
 315
 316 template <typename Fn>
 317 void forEachOptionName(const DocumentedOption &Option, const Record *DocInfo,
 318                        Fn F) {
 319   F(Option.Option);
 320
 321   for (auto *Alias : Option.Aliases)
 322     if (!isExcluded(Alias, DocInfo) && canSphinxCopeWithOption(Option.Option))
 323       F(Alias);
 324 }
 325
 326 void emitOption(const DocumentedOption &Option, const Record *DocInfo,
 327                 raw_ostream &OS) {
 328   if (isExcluded(Option.Option, DocInfo))
 329     return;
 330   if (DocInfo->getValue("IncludedFlags") && !isIncluded(Option.Option, DocInfo))
 331     return;
 332   if (Option.Option->getValueAsDef("Kind")->getName() == "KIND_UNKNOWN" ||
 333       Option.Option->getValueAsDef("Kind")->getName() == "KIND_INPUT")
 334     return;
 335   if (!canSphinxCopeWithOption(Option.Option))
 336     return;
 337
 338   // HACK: Emit a different program name with each option to work around
 339   // sphinx's inability to cope with options that differ only by punctuation
 340   // (eg -ObjC vs -ObjC++, -G vs -G=).
 341   std::vector<std::string> SphinxOptionIDs;
 342   forEachOptionName(Option, DocInfo, [&](const Record *Option) {
 343     for (auto &Prefix : Option->getValueAsListOfStrings("Prefixes"))
 344       SphinxOptionIDs.push_back(std::string(getSphinxOptionID(
 345           (Prefix + Option->getValueAsString("Name")).str())));
 346   });
 347   assert(!SphinxOptionIDs.empty() && "no flags for option");
 348   static std::map<std::string, int> NextSuffix;
 349   int SphinxWorkaroundSuffix = NextSuffix[*std::max_element(
 350       SphinxOptionIDs.begin(), SphinxOptionIDs.end(),
 351       [&](const std::string &A, const std::string &B) {
 352         return NextSuffix[A] < NextSuffix[B];
 353       })];
 354   for (auto &S : SphinxOptionIDs)
 355     NextSuffix[S] = SphinxWorkaroundSuffix + 1;
 356   if (SphinxWorkaroundSuffix)
 357     OS << ".. program:: " << DocInfo->getValueAsString("Program")
 358        << SphinxWorkaroundSuffix << "\n";
 359
 360   // Emit the names of the option.
 361   OS << ".. option:: ";
 362   bool EmittedAny = false;
 363   forEachOptionName(Option, DocInfo, [&](const Record *Option) {
 364     EmittedAny = emitOptionNames(Option, OS, EmittedAny);
 365   });
 366   if (SphinxWorkaroundSuffix)
 367     OS << "\n.. program:: " << DocInfo->getValueAsString("Program");
 368   OS << "\n\n";
 369
 370   // Emit the description, if we have one.
 371   const Record *R = Option.Option;
 372   std::string Description =
 373       getRSTStringWithTextFallback(R, "DocBrief", "HelpText");
 374
 375   if (!isa<UnsetInit>(R->getValueInit("Values"))) {
 376     if (!Description.empty() && Description.back() != '.')
 377       Description.push_back('.');
 378
 379     StringRef MetaVarName;
 380     if (!isa<UnsetInit>(R->getValueInit("MetaVarName")))
 381       MetaVarName = R->getValueAsString("MetaVarName");
 382     else
 383       MetaVarName = DefaultMetaVarName;
 384
 385     SmallVector<StringRef> Values;
 386     SplitString(R->getValueAsString("Values"), Values, ",");
 387     Description += (" " + MetaVarName + " must be '").str();
 388     if (Values.size() > 1) {
 389       Description += join(Values.begin(), Values.end() - 1, "', '");
 390       Description += "' or '";
 391     }
 392     Description += (Values.back() + "'.").str();
 393   }
 394
 395   if (!Description.empty())
 396     OS << Description << "\n\n";
 397 }
 398
 399 void emitDocumentation(int Depth, const Documentation &Doc,
 400                        const Record *DocInfo, raw_ostream &OS);
 401
 402 void emitGroup(int Depth, const DocumentedGroup &Group, const Record *DocInfo,
 403                raw_ostream &OS) {
 404   if (isExcluded(Group.Group, DocInfo))
 405     return;
 406
 407   if (DocInfo->getValue("IncludedFlags") && !isGroupIncluded(Group, DocInfo))
 408     return;
 409
 410   emitHeading(Depth,
 411               getRSTStringWithTextFallback(Group.Group, "DocName", "Name"), OS);
 412
 413   // Emit the description, if we have one.
 414   std::string Description =
 415       getRSTStringWithTextFallback(Group.Group, "DocBrief", "HelpText");
 416   if (!Description.empty())
 417     OS << Description << "\n\n";
 418
 419   // Emit contained options and groups.
 420   emitDocumentation(Depth + 1, Group, DocInfo, OS);
 421 }
 422
 423 void emitDocumentation(int Depth, const Documentation &Doc,
 424                        const Record *DocInfo, raw_ostream &OS) {
 425   for (auto &O : Doc.Options)
 426     emitOption(O, DocInfo, OS);
 427   for (auto &G : Doc.Groups)
 428     emitGroup(Depth, G, DocInfo, OS);
 429 }
 430
 431 }  // namespace
 432
 433 void clang::EmitClangOptDocs(RecordKeeper &Records, raw_ostream &OS) {
 434   const Record *DocInfo = Records.getDef("GlobalDocumentation");
 435   if (!DocInfo) {
 436     PrintFatalError("The GlobalDocumentation top-level definition is missing, "
 437                     "no documentation will be generated.");
 438     return;
 439   }
 440   OS << DocInfo->getValueAsString("Intro") << "\n";
 441   OS << ".. program:: " << DocInfo->getValueAsString("Program") << "\n";
 442
 443   emitDocumentation(0, extractDocumentation(Records), DocInfo, OS);
 444 }