|
|
@@ -0,0 +1,358 @@ |
|
|
//===- ClangOptionDocEmitter.cpp - Documentation for command line flags ---===// |
|
|
// |
|
|
// The LLVM Compiler Infrastructure |
|
|
// |
|
|
// This file is distributed under the University of Illinois Open Source |
|
|
// License. See LICENSE.TXT for details. |
|
|
// |
|
|
// FIXME: Once this has stabilized, consider moving it to LLVM. |
|
|
// |
|
|
//===----------------------------------------------------------------------===// |
|
|
|
|
|
#include "llvm/TableGen/Error.h" |
|
|
#include "llvm/ADT/STLExtras.h" |
|
|
#include "llvm/ADT/SmallString.h" |
|
|
#include "llvm/ADT/StringSwitch.h" |
|
|
#include "llvm/ADT/Twine.h" |
|
|
#include "llvm/TableGen/Record.h" |
|
|
#include "llvm/TableGen/TableGenBackend.h" |
|
|
#include <cctype> |
|
|
#include <cstring> |
|
|
#include <map> |
|
|
|
|
|
using namespace llvm; |
|
|
|
|
|
namespace clang { |
|
|
namespace docs { |
|
|
namespace { |
|
|
struct DocumentedOption { |
|
|
Record *Option; |
|
|
std::vector<Record*> Aliases; |
|
|
}; |
|
|
struct DocumentedGroup; |
|
|
struct Documentation { |
|
|
std::vector<DocumentedGroup> Groups; |
|
|
std::vector<DocumentedOption> Options; |
|
|
}; |
|
|
struct DocumentedGroup : Documentation { |
|
|
Record *Group; |
|
|
}; |
|
|
|
|
|
// Reorganize the records into a suitable form for emitting documentation. |
|
|
Documentation extractDocumentation(RecordKeeper &Records) { |
|
|
Documentation Result; |
|
|
|
|
|
// Build the tree of groups. The root in the tree is the fake option group |
|
|
// (Record*)nullptr, which contains all top-level groups and options. |
|
|
std::map<Record*, std::vector<Record*> > OptionsInGroup; |
|
|
std::map<Record*, std::vector<Record*> > GroupsInGroup; |
|
|
std::map<Record*, std::vector<Record*> > Aliases; |
|
|
|
|
|
std::map<std::string, Record*> OptionsByName; |
|
|
for (Record *R : Records.getAllDerivedDefinitions("Option")) |
|
|
OptionsByName[R->getValueAsString("Name")] = R; |
|
|
|
|
|
auto Flatten = [](Record *R) { |
|
|
return R->getValue("DocFlatten") && R->getValueAsBit("DocFlatten"); |
|
|
}; |
|
|
|
|
|
auto SkipFlattened = [&](Record *R) -> Record* { |
|
|
while (R && Flatten(R)) { |
|
|
auto *G = dyn_cast<DefInit>(R->getValueInit("Group")); |
|
|
if (!G) |
|
|
return nullptr; |
|
|
R = G->getDef(); |
|
|
} |
|
|
return R; |
|
|
}; |
|
|
|
|
|
for (Record *R : Records.getAllDerivedDefinitions("OptionGroup")) { |
|
|
if (Flatten(R)) |
|
|
continue; |
|
|
|
|
|
Record *Group = nullptr; |
|
|
if (auto *G = dyn_cast<DefInit>(R->getValueInit("Group"))) |
|
|
Group = SkipFlattened(G->getDef()); |
|
|
GroupsInGroup[Group].push_back(R); |
|
|
} |
|
|
|
|
|
for (Record *R : Records.getAllDerivedDefinitions("Option")) { |
|
|
if (auto *A = dyn_cast<DefInit>(R->getValueInit("Alias"))) { |
|
|
Aliases[A->getDef()].push_back(R); |
|
|
continue; |
|
|
} |
|
|
|
|
|
// Pretend no-X and Xno-Y options are aliases of X and XY. |
|
|
auto Name = R->getValueAsString("Name"); |
|
|
if (Name.size() >= 4) { |
|
|
if (Name.substr(0, 3) == "no-" && OptionsByName[Name.substr(3)]) { |
|
|
Aliases[OptionsByName[Name.substr(3)]].push_back(R); |
|
|
continue; |
|
|
} |
|
|
if (Name.substr(1, 3) == "no-" && OptionsByName[Name[0] + Name.substr(4)]) { |
|
|
Aliases[OptionsByName[Name[0] + Name.substr(4)]].push_back(R); |
|
|
continue; |
|
|
} |
|
|
} |
|
|
|
|
|
Record *Group = nullptr; |
|
|
if (auto *G = dyn_cast<DefInit>(R->getValueInit("Group"))) |
|
|
Group = SkipFlattened(G->getDef()); |
|
|
OptionsInGroup[Group].push_back(R); |
|
|
} |
|
|
|
|
|
auto CompareByName = [](Record *A, Record *B) { |
|
|
return A->getValueAsString("Name") < B->getValueAsString("Name"); |
|
|
}; |
|
|
|
|
|
auto CompareByLocation = [](Record *A, Record *B) { |
|
|
return A->getLoc()[0].getPointer() < B->getLoc()[0].getPointer(); |
|
|
}; |
|
|
|
|
|
auto DocumentationForOption = [&](Record *R) -> DocumentedOption { |
|
|
auto &A = Aliases[R]; |
|
|
std::sort(A.begin(), A.end(), CompareByName); |
|
|
return {R, std::move(A)}; |
|
|
}; |
|
|
|
|
|
std::function<Documentation(Record *)> DocumentationForGroup = |
|
|
[&](Record *R) -> Documentation { |
|
|
Documentation D; |
|
|
|
|
|
auto &Groups = GroupsInGroup[R]; |
|
|
std::sort(Groups.begin(), Groups.end(), CompareByLocation); |
|
|
for (Record *G : Groups) { |
|
|
D.Groups.emplace_back(); |
|
|
D.Groups.back().Group = G; |
|
|
Documentation &Base = D.Groups.back(); |
|
|
Base = DocumentationForGroup(G); |
|
|
} |
|
|
|
|
|
auto &Options = OptionsInGroup[R]; |
|
|
std::sort(Options.begin(), Options.end(), CompareByName); |
|
|
for (Record *O : Options) |
|
|
D.Options.push_back(DocumentationForOption(O)); |
|
|
|
|
|
return D; |
|
|
}; |
|
|
|
|
|
return DocumentationForGroup(nullptr); |
|
|
} |
|
|
|
|
|
// Get the first and successive separators to use for an OptionKind. |
|
|
std::pair<StringRef,StringRef> getSeparatorsForKind(Record *OptionKind) { |
|
|
return StringSwitch<std::pair<StringRef, StringRef>>(OptionKind->getName()) |
|
|
.Cases("KIND_JOINED", "KIND_JOINED_OR_SEPARATE", |
|
|
"KIND_JOINED_AND_SEPARATE", |
|
|
"KIND_REMAINING_ARGS_JOINED", {"", " "}) |
|
|
.Case("KIND_COMMAJOINED", {"", ","}) |
|
|
.Default({" ", " "}); |
|
|
} |
|
|
|
|
|
const unsigned UnlimitedArgs = unsigned(-1); |
|
|
|
|
|
// Get the number of arguments expected for an option, or -1 if any number of |
|
|
// arguments are accepted. |
|
|
unsigned getNumArgsForKind(Record *OptionKind, Record *Option) { |
|
|
return StringSwitch<unsigned>(OptionKind->getName()) |
|
|
.Cases("KIND_JOINED", "KIND_JOINED_OR_SEPARATE", "KIND_SEPARATE", 1) |
|
|
.Cases("KIND_REMAINING_ARGS", "KIND_REMAINING_ARGS_JOINED", |
|
|
"KIND_COMMAJOINED", UnlimitedArgs) |
|
|
.Case("KIND_JOINED_AND_SEPARATE", 2) |
|
|
.Case("KIND_MULTIARG", Option->getValueAsInt("NumArgs")) |
|
|
.Default(0); |
|
|
} |
|
|
|
|
|
bool hasFlag(const Record *OptionOrGroup, StringRef OptionFlag) { |
|
|
for (const Record *Flag : OptionOrGroup->getValueAsListOfDefs("Flags")) |
|
|
if (Flag->getName() == OptionFlag) |
|
|
return true; |
|
|
return false; |
|
|
} |
|
|
|
|
|
bool isExcluded(const Record *OptionOrGroup, const Record *DocInfo) { |
|
|
// FIXME: Provide a flag to specify the set of exclusions. |
|
|
for (StringRef Exclusion : DocInfo->getValueAsListOfStrings("ExcludedFlags")) |
|
|
if (hasFlag(OptionOrGroup, Exclusion)) |
|
|
return true; |
|
|
return false; |
|
|
} |
|
|
|
|
|
std::string escapeRST(StringRef Str) { |
|
|
std::string Out; |
|
|
for (auto K : Str) { |
|
|
if (StringRef("`*|_[]\\").count(K)) |
|
|
Out.push_back('\\'); |
|
|
Out.push_back(K); |
|
|
} |
|
|
return Out; |
|
|
} |
|
|
|
|
|
bool canSphinxCopeWithOption(const Record *Option) { |
|
|
// HACK: Work arond sphinx's inability to cope with punctuation-only options |
|
|
// such as /? by suppressing them from the option list. |
|
|
for (char C : Option->getValueAsString("Name")) |
|
|
if (isalnum(C)) |
|
|
return true; |
|
|
return false; |
|
|
} |
|
|
|
|
|
void emitHeading(int Depth, std::string Heading, raw_ostream &OS) { |
|
|
assert(Depth < 8 && "groups nested too deeply"); |
|
|
OS << Heading << '\n' |
|
|
<< std::string(Heading.size(), "=~-_'+<>"[Depth]) << "\n"; |
|
|
} |
|
|
|
|
|
/// Get the value of field \p Primary, if possible. If \p Primary does not |
|
|
/// exist, get the value of \p Fallback and escape it for rST emission. |
|
|
std::string getRSTStringWithTextFallback(const Record *R, StringRef Primary, |
|
|
StringRef Fallback) { |
|
|
for (auto Field : {Primary, Fallback}) { |
|
|
if (auto *V = R->getValue(Field)) { |
|
|
StringRef Value; |
|
|
if (auto *SV = dyn_cast_or_null<StringInit>(V->getValue())) |
|
|
Value = SV->getValue(); |
|
|
else if (auto *CV = dyn_cast_or_null<CodeInit>(V->getValue())) |
|
|
Value = CV->getValue(); |
|
|
if (!Value.empty()) |
|
|
return Field == Primary ? Value.str() : escapeRST(Value); |
|
|
} |
|
|
} |
|
|
return StringRef(); |
|
|
} |
|
|
|
|
|
void emitOptionWithArgs(StringRef Prefix, Record *Option, |
|
|
ArrayRef<std::string> Args, raw_ostream &OS) { |
|
|
OS << Prefix << escapeRST(Option->getValueAsString("Name")); |
|
|
|
|
|
std::pair<StringRef, StringRef> Separators = |
|
|
getSeparatorsForKind(Option->getValueAsDef("Kind")); |
|
|
|
|
|
StringRef Separator = Separators.first; |
|
|
for (auto Arg : Args) { |
|
|
OS << Separator << escapeRST(Arg); |
|
|
Separator = Separators.second; |
|
|
} |
|
|
} |
|
|
|
|
|
void emitOptionName(StringRef Prefix, Record *Option, raw_ostream &OS) { |
|
|
// Find the arguments to list after the option. |
|
|
unsigned NumArgs = getNumArgsForKind(Option->getValueAsDef("Kind"), Option); |
|
|
|
|
|
std::vector<std::string> Args; |
|
|
if (!Option->isValueUnset("MetaVarName")) |
|
|
Args.push_back(Option->getValueAsString("MetaVarName")); |
|
|
else if (NumArgs == 1) |
|
|
Args.push_back("<arg>"); |
|
|
|
|
|
while (Args.size() < NumArgs) { |
|
|
Args.push_back(("<arg" + Twine(Args.size() + 1) + ">").str()); |
|
|
// Use '--args <arg1> <arg2>...' if any number of args are allowed. |
|
|
if (Args.size() == 2 && NumArgs == UnlimitedArgs) { |
|
|
Args.back() += "..."; |
|
|
break; |
|
|
} |
|
|
} |
|
|
|
|
|
emitOptionWithArgs(Prefix, Option, Args, OS); |
|
|
|
|
|
auto AliasArgs = Option->getValueAsListOfStrings("AliasArgs"); |
|
|
if (!AliasArgs.empty()) { |
|
|
Record *Alias = Option->getValueAsDef("Alias"); |
|
|
OS << " (equivalent to "; |
|
|
emitOptionWithArgs(Alias->getValueAsListOfStrings("Prefixes").front(), |
|
|
Alias, Option->getValueAsListOfStrings("AliasArgs"), OS); |
|
|
OS << ")"; |
|
|
} |
|
|
} |
|
|
|
|
|
bool emitOptionNames(Record *Option, raw_ostream &OS, bool EmittedAny) { |
|
|
for (auto &Prefix : Option->getValueAsListOfStrings("Prefixes")) { |
|
|
if (EmittedAny) |
|
|
OS << ", "; |
|
|
emitOptionName(Prefix, Option, OS); |
|
|
EmittedAny = true; |
|
|
} |
|
|
return EmittedAny; |
|
|
} |
|
|
|
|
|
void emitOption(const DocumentedOption &Option, const Record *DocInfo, |
|
|
raw_ostream &OS) { |
|
|
if (isExcluded(Option.Option, DocInfo)) |
|
|
return; |
|
|
if (Option.Option->getValueAsDef("Kind")->getName() == "KIND_UNKNOWN" || |
|
|
Option.Option->getValueAsDef("Kind")->getName() == "KIND_INPUT") |
|
|
return; |
|
|
if (!canSphinxCopeWithOption(Option.Option)) |
|
|
return; |
|
|
|
|
|
// HACK: Emit a different program name with each option to work around |
|
|
// sphinx's inability to cope with options that differ only by punctuation |
|
|
// (eg -ObjC vs -ObjC++, -G vs -G=). |
|
|
static int Emitted = 0; |
|
|
OS << ".. program:: " << DocInfo->getValueAsString("Program") << Emitted++ |
|
|
<< "\n"; |
|
|
|
|
|
// Emit the names of the option. |
|
|
OS << ".. option:: "; |
|
|
bool EmittedAny = emitOptionNames(Option.Option, OS, false); |
|
|
for (auto *Alias : Option.Aliases) |
|
|
if (!isExcluded(Alias, DocInfo) && canSphinxCopeWithOption(Option.Option)) |
|
|
EmittedAny = emitOptionNames(Alias, OS, EmittedAny); |
|
|
assert(EmittedAny && "no flags for option"); |
|
|
OS << "\n\n"; |
|
|
|
|
|
// Emit the description, if we have one. |
|
|
std::string Description = |
|
|
getRSTStringWithTextFallback(Option.Option, "DocBrief", "HelpText"); |
|
|
if (!Description.empty()) |
|
|
OS << Description << "\n\n"; |
|
|
} |
|
|
|
|
|
void emitDocumentation(int Depth, const Documentation &Doc, |
|
|
const Record *DocInfo, raw_ostream &OS); |
|
|
|
|
|
void emitGroup(int Depth, const DocumentedGroup &Group, const Record *DocInfo, |
|
|
raw_ostream &OS) { |
|
|
if (isExcluded(Group.Group, DocInfo)) |
|
|
return; |
|
|
|
|
|
emitHeading(Depth, |
|
|
getRSTStringWithTextFallback(Group.Group, "DocName", "Name"), OS); |
|
|
|
|
|
// Emit the description, if we have one. |
|
|
std::string Description = |
|
|
getRSTStringWithTextFallback(Group.Group, "DocBrief", "HelpText"); |
|
|
if (!Description.empty()) |
|
|
OS << Description << "\n\n"; |
|
|
|
|
|
// Emit contained options and groups. |
|
|
emitDocumentation(Depth + 1, Group, DocInfo, OS); |
|
|
} |
|
|
|
|
|
void emitDocumentation(int Depth, const Documentation &Doc, |
|
|
const Record *DocInfo, raw_ostream &OS) { |
|
|
for (auto &O : Doc.Options) |
|
|
emitOption(O, DocInfo, OS); |
|
|
for (auto &G : Doc.Groups) |
|
|
emitGroup(Depth, G, DocInfo, OS); |
|
|
} |
|
|
|
|
|
} // namespace |
|
|
} // namespace docs |
|
|
|
|
|
void EmitClangOptDocs(RecordKeeper &Records, raw_ostream &OS) { |
|
|
using namespace docs; |
|
|
|
|
|
const Record *DocInfo = Records.getDef("GlobalDocumentation"); |
|
|
if (!DocInfo) { |
|
|
PrintFatalError("The GlobalDocumentation top-level definition is missing, " |
|
|
"no documentation will be generated."); |
|
|
return; |
|
|
} |
|
|
OS << DocInfo->getValueAsString("Intro") << "\n"; |
|
|
OS << ".. program:: " << DocInfo->getValueAsString("Program") << "\n"; |
|
|
|
|
|
emitDocumentation(0, extractDocumentation(Records), DocInfo, OS); |
|
|
} |
|
|
} // end namespace clang |