contrib/llvm/tools/clang/utils/TableGen/ClangOptionDocEmitter.cpp

   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.begin(), A.end(), 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.begin(), Groups.end(), 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.begin(), Options.end(), 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