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 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 179 std::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 189 StringRef 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 196 bool 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 205 void 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. 213 std::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 std::string(StringRef()); 227 } 228 229 void 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 243 void 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(std::string(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 283 bool 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 293 template <typename Fn> 294 void 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 303 void 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(std::string(getSphinxOptionID( 320 (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 352 void emitDocumentation(int Depth, const Documentation &Doc, 353 const Record *DocInfo, raw_ostream &OS); 354 355 void 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 373 void 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 383 void 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