| 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 |
} |