tclap 1.6.0
DocBookOutput.h
Go to the documentation of this file.
1// -*- Mode: c++; c-basic-offset: 4; tab-width: 4; -*-
2
3/******************************************************************************
4 *
5 * file: DocBookOutput.h
6 *
7 * Copyright (c) 2004, Michael E. Smoot
8 * Copyright (c) 2017, Google LLC
9 * All rights reserved.
10 *
11 * See the file COPYING in the top directory of this distribution for
12 * more information.
13 *
14 * THE SOFTWARE IS PROVIDED _AS IS_, WITHOUT WARRANTY OF ANY KIND, EXPRESS
15 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
17 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
20 * DEALINGS IN THE SOFTWARE.
21 *
22 *****************************************************************************/
23
24#ifndef TCLAP_DOC_BOOK_OUTPUT_H
25#define TCLAP_DOC_BOOK_OUTPUT_H
26
27#include <tclap/Arg.h>
28#include <tclap/ArgGroup.h>
30#include <tclap/CmdLineOutput.h>
31
32#include <algorithm>
33#include <iostream>
34#include <list>
35#include <string>
36#include <vector>
37
38namespace TCLAP {
39
45public:
51 void usage(CmdLineInterface &c) override;
52
58 void version(CmdLineInterface &c) override;
59
66 void failure(CmdLineInterface &c, ArgException &e) override;
67
69
70protected:
71 // Escape raw data once, at the XML output boundary (text and attributes).
72 static std::string escapeXml(const std::string &text) {
73 std::string result;
74 for (char character : text) {
75 switch (character) {
76 case '&': result += "&amp;"; break;
77 case '<': result += "&lt;"; break;
78 case '>': result += "&gt;"; break;
79 case '\"': result += "&quot;"; break;
80 case '\'': result += "&apos;"; break;
81 default: result += character; break;
82 }
83 }
84 return result;
85 }
86
87 static std::string valueLabel(const Arg &arg) {
88 const std::string id = arg.shortID();
89 const std::string label = arg.getFlag().empty()
90 ? arg.nameStartString() + arg.getName()
91 : arg.flagStartString() + arg.getFlag();
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);
99 }
100 return id; // Custom IDs without the usual value wrapper.
101 }
102
109 void substituteSpecialChars(std::string &s, char r,
110 const std::string &x) const;
111 void removeChar(std::string &s, char r) const;
112
113 void printShortGroup(const ArgGroup &group, bool labelsOnly);
114 static bool hasVisiblePositional(const ArgGroup &group) {
115 for (const Arg *arg : group)
116 if (!arg->hasLabel() && arg->visibleInHelp()) return true;
117 return false;
118 }
119
120 void printShortArg(Arg *it, bool required);
121 void printLongArg(const ArgGroup &it) const;
122
124
125private:
126 void _printSynopsis(CmdLineInterface &cmd,
127 const std::list<ArgGroup *> &groups,
128 const std::string &programName);
129 static ArgGroup *_findArgGroup(const std::list<ArgGroup *> &groups,
130 const Arg *arg);
131 void _printLongEntry(const Arg &arg, bool forceRequired) const;
132 void _printAliasTerms(const Arg &arg) const;
133 void _printValuePlaceholder(const Arg &arg) const;
134};
135
137 std::cout << _cmd.getVersion() << std::endl;
138}
139
140namespace internal {
141inline const char *GroupChoice(const ArgGroup &group) {
142 if (!group.showAsGroup()) {
143 return "plain";
144 }
145
146 if (group.isRequired()) {
147 return "req";
148 }
149
150 return "opt";
151}
152} // namespace internal
153
154inline void DocBookOutput::printShortGroup(const ArgGroup &group, bool labelsOnly) {
155 int visible = 0;
156 for (const Arg *arg : group)
157 if (arg->visibleInHelp() && (!labelsOnly || arg->hasLabel())) ++visible;
158 if (visible > 1)
159 std::cout << "<group choice='" << internal::GroupChoice(group) << "'>\n";
160 for (Arg *arg : group) {
161 if (!arg->visibleInHelp() || (labelsOnly && !arg->hasLabel())) continue;
162 printShortArg(arg, arg->isRequired() || (visible == 1 && group.isRequired()));
163 }
164 if (visible > 1) std::cout << "</group>\n";
165}
166
168 std::list<ArgGroup *> argSets = _cmd.getArgGroups();
169 std::string progName = _cmd.getProgramName();
170 std::string xversion = _cmd.getVersion();
171 theDelimiter = _cmd.getDelimiter();
172
173 std::cout << "<?xml version='1.0'?>\n";
174 std::cout
175 << "<!DOCTYPE refentry PUBLIC \"-//OASIS//DTD DocBook XML V4.2//EN\"\n";
176 std::cout
177 << "\t\"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd\">\n\n";
178
179 std::cout << "<refentry>\n";
180
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";
185
186 std::cout << "<refnamediv>\n";
187 std::cout << "<refname>" << escapeXml(progName) << "</refname>\n";
188 std::cout << "<refpurpose>" << escapeXml(_cmd.getMessage()) << "</refpurpose>\n";
189 std::cout << "</refnamediv>\n";
190
191 _printSynopsis(_cmd, argSets, progName);
192
193 std::cout << "<refsect1>\n";
194 std::cout << "<title>Description</title>\n";
195 std::cout << "<para>\n";
196 std::cout << escapeXml(_cmd.getMessage()) << '\n';
197 std::cout << "</para>\n";
198 std::cout << "</refsect1>\n";
199
200 std::cout << "<refsect1>\n";
201 std::cout << "<title>Options</title>\n";
202
203 std::cout << "<variablelist>\n";
204
205 for (ArgGroup *group : argSets) {
206 printLongArg(*group);
207 }
208
209 std::cout << "</variablelist>\n";
210 std::cout << "</refsect1>\n";
211
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";
218
219 std::cout << "</refentry>" << std::endl;
220}
221
223 static_cast<void>(_cmd); // unused
224 std::cout << e.what() << std::endl;
225 throw ExitException(1);
226}
227
228inline void DocBookOutput::substituteSpecialChars(std::string &s, char r,
229 const std::string &x) const {
230 size_t p;
231 while ((p = s.find_first_of(r)) != std::string::npos) {
232 s.erase(p, 1);
233 s.insert(p, x);
234 }
235}
236
237inline void DocBookOutput::removeChar(std::string &s, char r) const {
238 size_t p;
239 while ((p = s.find_first_of(r)) != std::string::npos) {
240 s.erase(p, 1);
241 }
242}
243
244inline void DocBookOutput::printShortArg(Arg *a, bool required) {
245
246 std::string choice = "opt";
247 if (required) {
248 choice = "plain";
249 }
250
251 std::cout << "<arg choice='" << choice << '\'';
252 if (a->acceptsMultipleValues()) std::cout << " rep='repeat'";
253
254 std::cout << '>';
255 if (!a->hasLabel()) {
256 std::cout << "<replaceable>" << escapeXml(a->getName())
257 << "</replaceable></arg>" << std::endl;
258 return;
259 }
260
261 if (!a->getFlag().empty())
262 std::cout << escapeXml(std::string(1, a->flagStartChar()) + a->getFlag());
263 else
264 std::cout << escapeXml(a->nameStartString() + a->getName());
265 if (a->isValueRequired()) {
266 _printValuePlaceholder(*a);
267 }
268 std::cout << "</arg>" << std::endl;
269}
270
271inline void DocBookOutput::printLongArg(const ArgGroup &group) const {
272
273 bool forceRequired = group.isRequired() && CountVisibleArgs(group) == 1;
274 for (const Arg *arg : group) {
275 const Arg &a = *arg;
276 if (!a.visibleInHelp()) {
277 continue;
278 }
279 _printLongEntry(a, forceRequired);
280 }
281}
282
283inline void DocBookOutput::_printSynopsis(CmdLineInterface &cmd,
284 const std::list<ArgGroup *> &groups,
285 const std::string &programName) {
286 std::cout << "<refsynopsisdiv>\n";
287 std::cout << "<cmdsynopsis>\n";
288
289 std::cout << "<command>" << escapeXml(programName) << "</command>\n";
290
291 for (const ArgGroup *groupPtr : groups) {
292 const ArgGroup &group = *groupPtr;
293 if (group.isExclusive() && hasVisiblePositional(group)) continue;
294 printShortGroup(group, true);
295 }
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()) {
303 printShortGroup(*owner, false);
304 shown.push_back(owner);
305 }
306 } else {
307 printShortArg(arg, arg->isRequired());
308 }
309 }
310
311 std::cout << "</cmdsynopsis>\n";
312 std::cout << "</refsynopsisdiv>\n";
313}
314
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;
319 return nullptr;
320}
321
322inline void DocBookOutput::_printLongEntry(const Arg &a,
323 bool forceRequired) const {
324 std::string desc = a.getDescription(forceRequired || a.isRequired());
325
326 std::cout << "<varlistentry>\n";
327 if (!a.hasLabel()) {
328 std::cout << "<term><replaceable>" << escapeXml(a.getName())
329 << "</replaceable></term>\n<listitem><para>"
330 << escapeXml(desc) << "</para></listitem>\n</varlistentry>"
331 << std::endl;
332 return;
333 }
334
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";
341 }
342
343 std::cout << "<term>\n";
344 std::cout << "<option>";
345 std::cout << escapeXml(a.nameStartString() + a.getName());
346 if (a.isValueRequired()) {
347 _printValuePlaceholder(a);
348 }
349
350 std::cout << "</option>\n";
351 std::cout << "</term>\n";
352
353 _printAliasTerms(a);
354
355 std::cout << "<listitem>\n";
356 std::cout << "<para>\n";
357 std::cout << escapeXml(desc) << '\n';
358 std::cout << "</para>\n";
359 std::cout << "</listitem>\n";
360
361 std::cout << "</varlistentry>" << std::endl;
362}
363
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()) +
372 label);
373 if (a.isValueRequired())
374 std::cout << escapeXml(std::string(1, theDelimiter))
375 << "<replaceable>" << escapeXml(valueLabel(a))
376 << "</replaceable>";
377 std::cout << "</option></term>\n";
378 }
379 }
380}
381
382inline void DocBookOutput::_printValuePlaceholder(const Arg &arg) const {
383 const std::string label = valueLabel(arg);
384 std::cout << escapeXml(std::string(1, theDelimiter));
385 std::cout << "<replaceable>" << escapeXml(label) << "</replaceable>";
386}
387
388} // namespace TCLAP
389#endif // TCLAP_DOC_BOOK_OUTPUT_H
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...
Definition ArgGroup.h:42
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.
Definition ArgGroup.h:107
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.
Definition Arg.h:69
static std::string flagStartString()
Definition Arg.h:266
bool isValueRequired() const noexcept
Indicates whether a value must be specified for argument.
Definition Arg.h:763
static constexpr char flagStartChar() noexcept
Definition Arg.h:256
virtual bool acceptsMultipleValues()
Use by output classes to determine whether an Arg accepts multiple values.
Definition Arg.h:821
const std::string & getName() const noexcept
Returns the argument name.
Definition Arg.h:759
static std::string nameStartString()
Definition Arg.h:275
const std::string & getFlag() const noexcept
Returns the argument flag.
Definition Arg.h:757
virtual bool hasLabel() const
Definition Arg.h:449
virtual bool visibleInHelp() const
Returns true if this Arg is visible in the help output.
Definition Arg.h:447
virtual std::string shortID(const std::string &valueId="val") const
Returns a short ID for the usage.
Definition Arg.h:590
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.
Definition Arg.h:54
int CountVisibleArgs(const ArgGroup &g)
Definition ArgGroup.h:248