24#ifndef TCLAP_DOC_BOOK_OUTPUT_H
25#define TCLAP_DOC_BOOK_OUTPUT_H
72 static std::string
escapeXml(
const std::string &text) {
74 for (
char character : text) {
76 case '&': result +=
"&";
break;
77 case '<': result +=
"<";
break;
78 case '>': result +=
">";
break;
79 case '\"': result +=
""";
break;
80 case '\'': result +=
"'";
break;
81 default: result += character;
break;
88 const std::string
id = arg.
shortID();
89 const std::string label = arg.
getFlag().empty()
92 const std::string::size_type labelStart =
id.find(label);
93 if (labelStart != std::string::npos) {
94 const std::string::size_type open = labelStart + label.size() + 1;
95 const std::string::size_type close =
id.rfind(
'>');
96 if (open <
id.size() &&
id[open] ==
'<' &&
97 close != std::string::npos && close > open)
98 return id.substr(open + 1, close - open - 1);
110 const std::string &x)
const;
111 void removeChar(std::string &s,
char r)
const;
115 for (
const Arg *arg : group)
116 if (!arg->hasLabel() && arg->visibleInHelp())
return true;
127 const std::list<ArgGroup *> &groups,
128 const std::string &programName);
129 static ArgGroup *_findArgGroup(
const std::list<ArgGroup *> &groups,
131 void _printLongEntry(
const Arg &arg,
bool forceRequired)
const;
132 void _printAliasTerms(
const Arg &arg)
const;
133 void _printValuePlaceholder(
const Arg &arg)
const;
141inline const char *GroupChoice(
const ArgGroup &group) {
156 for (
const Arg *arg : group)
157 if (arg->visibleInHelp() && (!labelsOnly || arg->hasLabel())) ++visible;
159 std::cout <<
"<group choice='" << internal::GroupChoice(group) <<
"'>\n";
160 for (
Arg *arg : group) {
161 if (!arg->visibleInHelp() || (labelsOnly && !arg->hasLabel()))
continue;
164 if (visible > 1) std::cout <<
"</group>\n";
173 std::cout <<
"<?xml version='1.0'?>\n";
175 <<
"<!DOCTYPE refentry PUBLIC \"-//OASIS//DTD DocBook XML V4.2//EN\"\n";
177 <<
"\t\"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd\">\n\n";
179 std::cout <<
"<refentry>\n";
181 std::cout <<
"<refmeta>\n";
182 std::cout <<
"<refentrytitle>" <<
escapeXml(progName) <<
"</refentrytitle>\n";
183 std::cout <<
"<manvolnum>1</manvolnum>\n";
184 std::cout <<
"</refmeta>\n";
186 std::cout <<
"<refnamediv>\n";
187 std::cout <<
"<refname>" <<
escapeXml(progName) <<
"</refname>\n";
189 std::cout <<
"</refnamediv>\n";
191 _printSynopsis(_cmd, argSets, progName);
193 std::cout <<
"<refsect1>\n";
194 std::cout <<
"<title>Description</title>\n";
195 std::cout <<
"<para>\n";
197 std::cout <<
"</para>\n";
198 std::cout <<
"</refsect1>\n";
200 std::cout <<
"<refsect1>\n";
201 std::cout <<
"<title>Options</title>\n";
203 std::cout <<
"<variablelist>\n";
209 std::cout <<
"</variablelist>\n";
210 std::cout <<
"</refsect1>\n";
212 std::cout <<
"<refsect1>\n";
213 std::cout <<
"<title>Version</title>\n";
214 std::cout <<
"<para>\n";
215 std::cout <<
escapeXml(xversion) <<
'\n';
216 std::cout <<
"</para>\n";
217 std::cout <<
"</refsect1>\n";
219 std::cout <<
"</refentry>" << std::endl;
223 static_cast<void>(_cmd);
224 std::cout << e.
what() << std::endl;
229 const std::string &x)
const {
231 while ((p = s.find_first_of(r)) != std::string::npos) {
239 while ((p = s.find_first_of(r)) != std::string::npos) {
246 std::string choice =
"opt";
251 std::cout <<
"<arg choice='" << choice <<
'\'';
257 <<
"</replaceable></arg>" << std::endl;
266 _printValuePlaceholder(*a);
268 std::cout <<
"</arg>" << std::endl;
274 for (
const Arg *arg : group) {
279 _printLongEntry(a, forceRequired);
284 const std::list<ArgGroup *> &groups,
285 const std::string &programName) {
286 std::cout <<
"<refsynopsisdiv>\n";
287 std::cout <<
"<cmdsynopsis>\n";
289 std::cout <<
"<command>" <<
escapeXml(programName) <<
"</command>\n";
291 for (
const ArgGroup *groupPtr : groups) {
296 const std::list<Arg *> operands = cmd.
getArgList();
297 std::list<ArgGroup *> shown;
298 for (Arg *arg : operands) {
299 if (arg->hasLabel() || !arg->visibleInHelp())
continue;
300 ArgGroup *owner = _findArgGroup(groups, arg);
301 if (owner && owner->isExclusive()) {
302 if (std::ranges::find(shown, owner) == shown.end()) {
304 shown.push_back(owner);
311 std::cout <<
"</cmdsynopsis>\n";
312 std::cout <<
"</refsynopsisdiv>\n";
315inline ArgGroup *DocBookOutput::_findArgGroup(
316 const std::list<ArgGroup *> &groups,
const Arg *arg) {
317 for (ArgGroup *group : groups)
318 if (std::ranges::find(*group, arg) != group->end()) return group;
322inline void DocBookOutput::_printLongEntry(
const Arg &a,
323 bool forceRequired)
const {
324 std::string desc = a.getDescription(forceRequired || a.isRequired());
326 std::cout <<
"<varlistentry>\n";
328 std::cout <<
"<term><replaceable>" <<
escapeXml(a.getName())
329 <<
"</replaceable></term>\n<listitem><para>"
330 <<
escapeXml(desc) <<
"</para></listitem>\n</varlistentry>"
335 if (!a.getFlag().empty()) {
336 std::cout <<
"<term>\n";
337 std::cout <<
"<option>";
338 std::cout <<
escapeXml(std::string(1, a.flagStartChar()) + a.getFlag());
339 std::cout <<
"</option>\n";
340 std::cout <<
"</term>\n";
343 std::cout <<
"<term>\n";
344 std::cout <<
"<option>";
345 std::cout <<
escapeXml(a.nameStartString() + a.getName());
346 if (a.isValueRequired()) {
347 _printValuePlaceholder(a);
350 std::cout <<
"</option>\n";
351 std::cout <<
"</term>\n";
355 std::cout <<
"<listitem>\n";
356 std::cout <<
"<para>\n";
358 std::cout <<
"</para>\n";
359 std::cout <<
"</listitem>\n";
361 std::cout <<
"</varlistentry>" << std::endl;
364inline void DocBookOutput::_printAliasTerms(
const Arg &a)
const {
365 for (
const auto &alias : a.aliases()) {
366 for (
int spelling = 0; spelling < 2; ++spelling) {
367 const std::string &label = spelling == 0 ? alias.flag : alias.name;
368 if (label.empty())
continue;
369 std::cout <<
"<term><option>"
370 <<
escapeXml((spelling == 0 ? a.flagStartString()
371 : a.nameStartString()) +
373 if (a.isValueRequired())
377 std::cout <<
"</option></term>\n";
382inline void DocBookOutput::_printValuePlaceholder(
const Arg &arg)
const {
385 std::cout <<
"<replaceable>" <<
escapeXml(label) <<
"</replaceable>";
A simple class that defines and argument exception.
const char * what() const noexcept override
Returns the arg id and error text.
ArgGroup is the base class for implementing groups of arguments that are mutually exclusive (it repla...
virtual bool isExclusive() const =0
Returns true if this argument group is exclusive.
virtual bool showAsGroup() const
If arguments in this group should show up as grouped in help.
virtual bool isRequired() const =0
Returns true if this argument group is required.
A virtual base class that defines the essential data for all arguments.
static std::string flagStartString()
bool isValueRequired() const noexcept
Indicates whether a value must be specified for argument.
static constexpr char flagStartChar() noexcept
virtual bool acceptsMultipleValues()
Use by output classes to determine whether an Arg accepts multiple values.
const std::string & getName() const noexcept
Returns the argument name.
static std::string nameStartString()
const std::string & getFlag() const noexcept
Returns the argument flag.
virtual bool hasLabel() const
virtual bool visibleInHelp() const
Returns true if this Arg is visible in the help output.
virtual std::string shortID(const std::string &valueId="val") const
Returns a short ID for the usage.
The base class that manages the command line definition and passes along the parsing to the appropria...
virtual std::string getVersion() const =0
Returns the version string.
virtual std::string getMessage() const =0
Returns the message string.
virtual std::string getProgramName() const =0
Returns the program name string.
virtual std::list< ArgGroup * > getArgGroups()=0
Returns the list of ArgGroups.
virtual char getDelimiter() const =0
Returns the delimiter string.
virtual std::list< Arg * > getArgList() const =0
The interface that any output object must implement.
A class that generates DocBook output for usage() method for the given CmdLine and its Args.
void printLongArg(const ArgGroup &it) const
static std::string valueLabel(const Arg &arg)
void substituteSpecialChars(std::string &s, char r, const std::string &x) const
Substitutes the char r for string x in string s.
static std::string escapeXml(const std::string &text)
void printShortArg(Arg *it, bool required)
void failure(CmdLineInterface &c, ArgException &e) override
Prints (to stderr) an error message, short usage Can be overridden to produce alternative behavior.
void usage(CmdLineInterface &c) override
Prints the usage to stdout.
void version(CmdLineInterface &c) override
Prints the version to stdout.
void removeChar(std::string &s, char r) const
void printShortGroup(const ArgGroup &group, bool labelsOnly)
static bool hasVisiblePositional(const ArgGroup &group)
Thrown when TCLAP thinks the program should exit.
int CountVisibleArgs(const ArgGroup &g)