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     auto 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     std::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     std::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     std::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<std::string> 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
 249   std::vector<std::string> Args;
 250   if (!Option->isValueUnset("MetaVarName"))
 251     Args.push_back(Option->getValueAsString("MetaVarName"));
 252   else if (NumArgs == 1)
 253     Args.push_back("<arg>");
 254
 255   while (Args.size() < NumArgs) {
 256     Args.push_back(("<arg" + Twine(Args.size() + 1) + ">").str());
 257     // Use '--args <arg1> <arg2>...' if any number of args are allowed.
 258     if (Args.size() == 2 && NumArgs == UnlimitedArgs) {
 259       Args.back() += "...";
 260       break;
 261     }
 262   }
 263
 264   emitOptionWithArgs(Prefix, Option, Args, OS);
 265
 266   auto AliasArgs = Option->getValueAsListOfStrings("AliasArgs");
 267   if (!AliasArgs.empty()) {
 268     Record *Alias = Option->getValueAsDef("Alias");
 269     OS << " (equivalent to ";
 270     emitOptionWithArgs(Alias->getValueAsListOfStrings("Prefixes").front(),
 271                        Alias, Option->getValueAsListOfStrings("AliasArgs"), OS);
 272     OS << ")";
 273   }
 274 }
 275
 276 bool emitOptionNames(const Record *Option, raw_ostream &OS, bool EmittedAny) {
 277   for (auto &Prefix : Option->getValueAsListOfStrings("Prefixes")) {
 278     if (EmittedAny)
 279       OS << ", ";
 280     emitOptionName(Prefix, Option, OS);
 281     EmittedAny = true;
 282   }
 283   return EmittedAny;
 284 }
 285
 286 template <typename Fn>
 287 void forEachOptionName(const DocumentedOption &Option, const Record *DocInfo,
 288                        Fn F) {
 289   F(Option.Option);
 290
 291   for (auto *Alias : Option.Aliases)
 292     if (!isExcluded(Alias, DocInfo) && canSphinxCopeWithOption(Option.Option))
 293       F(Alias);
 294 }
 295
 296 void emitOption(const DocumentedOption &Option, const Record *DocInfo,
 297                 raw_ostream &OS) {
 298   if (isExcluded(Option.Option, DocInfo))
 299     return;
 300   if (Option.Option->getValueAsDef("Kind")->getName() == "KIND_UNKNOWN" ||
 301       Option.Option->getValueAsDef("Kind")->getName() == "KIND_INPUT")
 302     return;
 303   if (!canSphinxCopeWithOption(Option.Option))
 304     return;
 305
 306   // HACK: Emit a different program name with each option to work around
 307   // sphinx's inability to cope with options that differ only by punctuation
 308   // (eg -ObjC vs -ObjC++, -G vs -G=).
 309   std::vector<std::string> SphinxOptionIDs;
 310   forEachOptionName(Option, DocInfo, [&](const Record *Option) {
 311     for (auto &Prefix : Option->getValueAsListOfStrings("Prefixes"))
 312       SphinxOptionIDs.push_back(
 313           getSphinxOptionID(Prefix + Option->getValueAsString("Name")));
 314   });
 315   assert(!SphinxOptionIDs.empty() && "no flags for option");
 316   static std::map<std::string, int> NextSuffix;
 317   int SphinxWorkaroundSuffix = NextSuffix[*std::max_element(
 318       SphinxOptionIDs.begin(), SphinxOptionIDs.end(),
 319       [&](const std::string &A, const std::string &B) {
 320         return NextSuffix[A] < NextSuffix[B];
 321       })];
 322   for (auto &S : SphinxOptionIDs)
 323     NextSuffix[S] = SphinxWorkaroundSuffix + 1;
 324   if (SphinxWorkaroundSuffix)
 325     OS << ".. program:: " << DocInfo->getValueAsString("Program")
 326        << SphinxWorkaroundSuffix << "\n";
 327
 328   // Emit the names of the option.
 329   OS << ".. option:: ";
 330   bool EmittedAny = false;
 331   forEachOptionName(Option, DocInfo, [&](const Record *Option) {
 332     EmittedAny = emitOptionNames(Option, OS, EmittedAny);
 333   });
 334   if (SphinxWorkaroundSuffix)
 335     OS << "\n.. program:: " << DocInfo->getValueAsString("Program");
 336   OS << "\n\n";
 337
 338   // Emit the description, if we have one.
 339   std::string Description =
 340       getRSTStringWithTextFallback(Option.Option, "DocBrief", "HelpText");
 341   if (!Description.empty())
 342     OS << Description << "\n\n";
 343 }
 344
 345 void emitDocumentation(int Depth, const Documentation &Doc,
 346                        const Record *DocInfo, raw_ostream &OS);
 347
 348 void emitGroup(int Depth, const DocumentedGroup &Group, const Record *DocInfo,
 349                raw_ostream &OS) {
 350   if (isExcluded(Group.Group, DocInfo))
 351     return;
 352
 353   emitHeading(Depth,
 354               getRSTStringWithTextFallback(Group.Group, "DocName", "Name"), OS);
 355
 356   // Emit the description, if we have one.
 357   std::string Description =
 358       getRSTStringWithTextFallback(Group.Group, "DocBrief", "HelpText");
 359   if (!Description.empty())
 360     OS << Description << "\n\n";
 361
 362   // Emit contained options and groups.
 363   emitDocumentation(Depth + 1, Group, DocInfo, OS);
 364 }
 365
 366 void emitDocumentation(int Depth, const Documentation &Doc,
 367                        const Record *DocInfo, raw_ostream &OS) {
 368   for (auto &O : Doc.Options)
 369     emitOption(O, DocInfo, OS);
 370   for (auto &G : Doc.Groups)
 371     emitGroup(Depth, G, DocInfo, OS);
 372 }
 373
 374 }  // namespace
 375 }  // namespace docs
 376
 377 void EmitClangOptDocs(RecordKeeper &Records, raw_ostream &OS) {
 378   using namespace docs;
 379
 380   const Record *DocInfo = Records.getDef("GlobalDocumentation");
 381   if (!DocInfo) {
 382     PrintFatalError("The GlobalDocumentation top-level definition is missing, "
 383                     "no documentation will be generated.");
 384     return;
 385   }
 386   OS << DocInfo->getValueAsString("Intro") << "\n";
 387   OS << ".. program:: " << DocInfo->getValueAsString("Program") << "\n";
 388
 389   emitDocumentation(0, extractDocumentation(Records), DocInfo, OS);
 390 }
 391 } // end namespace clang