1 /*
2 * The Lean Mean C++ Option Parser
3 *
4 * Copyright (C) 2012 Matthias S. Benkmann
5 *
6 * The "Software" in the following 2 paragraphs refers to this file containing
7 * the code to The Lean Mean C++ Option Parser.
8 * The "Software" does NOT refer to any other files which you
9 * may have received alongside this file (e.g. as part of a larger project that
10 * incorporates The Lean Mean C++ Option Parser).
11 *
12 * Permission is hereby granted, free of charge, to any person obtaining a copy
13 * of this software, to deal in the Software without restriction, including
14 * without limitation the rights to use, copy, modify, merge, publish,
15 * distribute, sublicense, and/or sell copies of the Software, and to permit
16 * persons to whom the Software is furnished to do so, subject to the following
17 * conditions:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
20 *
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * SOFTWARE.
28 */
29
30 /*
31 * NOTE: It is recommended that you read the processed HTML doxygen documentation
32 * rather than this source. If you don't know doxygen, it's like javadoc for C++.
33 * If you don't want to install doxygen you can find a copy of the processed
34 * documentation at
35 *
36 * http://optionparser.sourceforge.net/
37 *
38 */
39
40 /**
41 * @file
42 *
43 * @brief This is the only file required to use The Lean Mean C++ Option Parser.
44 * Just \#include it and you're set.
45 *
46 * The Lean Mean C++ Option Parser handles the program's command line arguments
47 * (argc, argv).
48 * It supports the short and long option formats of getopt(), getopt_long()
49 * and getopt_long_only() but has a more convenient interface.
50 * The following features set it apart from other option parsers:
51 *
52 * @par Highlights:
53 * <ul style="padding-left:1em;margin-left:0">
54 * <li> It is a header-only library. Just <code>\#include "optionparser.h"</code> and you're set.
55 * <li> It is freestanding. There are no dependencies whatsoever, not even the
56 * C or C++ standard library.
57 * <li> It has a usage message formatter that supports column alignment and
58 * line wrapping. This aids localization because it adapts to
59 * translated strings that are shorter or longer (even if they contain
60 * Asian wide characters).
61 * <li> Unlike getopt() and derivatives it doesn't force you to loop through
62 * options sequentially. Instead you can access options directly like this:
63 * <ul style="margin-top:.5em">
64 * <li> Test for presence of a switch in the argument vector:
65 * @code if ( options[QUIET] ) ... @endcode
66 * <li> Evaluate --enable-foo/--disable-foo pair where the last one used wins:
67 * @code if ( options[FOO].last()->type() == DISABLE ) ... @endcode
68 * <li> Cumulative option (-v verbose, -vv more verbose, -vvv even more verbose):
69 * @code int verbosity = options[VERBOSE].count(); @endcode
70 * <li> Iterate over all --file=<fname> arguments:
71 * @code for (Option* opt = options[FILE]; opt; opt = opt->next())
72 * fname = opt->arg; ... @endcode
73 * <li> If you really want to, you can still process all arguments in order:
74 * @code
75 * for (int i = 0; i < p.optionsCount(); ++i) {
76 * Option& opt = buffer[i];
77 * switch(opt.index()) {
78 * case HELP: ...
79 * case VERBOSE: ...
80 * case FILE: fname = opt.arg; ...
81 * case UNKNOWN: ...
82 * @endcode
83 * </ul>
84 * </ul> @n
85 * Despite these features the code size remains tiny.
86 * It is smaller than <a href="http://uclibc.org">uClibc</a>'s GNU getopt() and just a
87 * couple 100 bytes larger than uClibc's SUSv3 getopt(). @n
88 * (This does not include the usage formatter, of course. But you don't have to use that.)
89 *
90 * @par Download:
91 * Tarball with examples and test programs:
92 * <a style="font-size:larger;font-weight:bold" href="http://sourceforge.net/projects/optionparser/files/optionparser-1.4.tar.gz/download">optionparser-1.4.tar.gz</a> @n
93 * Just the header (this is all you really need):
94 * <a style="font-size:larger;font-weight:bold" href="http://optionparser.sourceforge.net/optionparser.h">optionparser.h</a>
95 *
96 * @par Changelog:
97 * <b>Version 1.4:</b> Fixed 2 printUsage() bugs that messed up output with small COLUMNS values @n
98 * <b>Version 1.3:</b> Compatible with Microsoft Visual C++. @n
99 * <b>Version 1.2:</b> Added @ref option::Option::namelen "Option::namelen" and removed the extraction
100 * of short option characters into a special buffer. @n
101 * Changed @ref option::Arg::Optional "Arg::Optional" to accept arguments if they are attached
102 * rather than separate. This is what GNU getopt() does and how POSIX recommends
103 * utilities should interpret their arguments.@n
104 * <b>Version 1.1:</b> Optional mode with argument reordering as done by GNU getopt(), so that
105 * options and non-options can be mixed. See
106 * @ref option::Parser::parse() "Parser::parse()".
107 *
108 * @par Feedback:
109 * Send questions, bug reports, feature requests etc. to: <tt><b>optionparser-feedback<span id="antispam"> (a) </span>lists.sourceforge.net</b></tt>
110 * @htmlonly <script type="text/javascript">document.getElementById("antispam").innerHTML="@"</script> @endhtmlonly
111 *
112 *
113 * @par Example program:
114 * (Note: @c option::* identifiers are links that take you to their documentation.)
115 * @code
116 * #error EXAMPLE SHORTENED FOR READABILITY. BETTER EXAMPLES ARE IN THE .TAR.GZ!
117 * #include <iostream>
118 * #include "optionparser.h"
119 *
120 * enum optionIndex { UNKNOWN, HELP, PLUS };
121 * const option::Descriptor usage[] =
122 * {
123 * {UNKNOWN, 0,"" , "" ,option::Arg::None, "USAGE: example [options]\n\n"
124 * "Options:" },
125 * {HELP, 0,"" , "help",option::Arg::None, " --help \tPrint usage and exit." },
126 * {PLUS, 0,"p", "plus",option::Arg::None, " --plus, -p \tIncrement count." },
127 * {UNKNOWN, 0,"" , "" ,option::Arg::None, "\nExamples:\n"
128 * " example --unknown -- --this_is_no_option\n"
129 * " example -unk --plus -ppp file1 file2\n" },
130 * {0,0,0,0,0,0}
131 * };
132 *
133 * int main(int argc, char* argv[])
134 * {
135 * argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present
136 * option::Stats stats(usage, argc, argv);
137 * option::Option options[stats.options_max], buffer[stats.buffer_max];
138 * option::Parser parse(usage, argc, argv, options, buffer);
139 *
140 * if (parse.error())
141 * return 1;
142 *
143 * if (options[HELP] || argc == 0) {
144 * option::printUsage(std::cout, usage);
145 * return 0;
146 * }
147 *
148 * std::cout << "--plus count: " <<
149 * options[PLUS].count() << "\n";
150 *
151 * for (option::Option* opt = options[UNKNOWN]; opt; opt = opt->next())
152 * std::cout << "Unknown option: " << opt->name << "\n";
153 *
154 * for (int i = 0; i < parse.nonOptionsCount(); ++i)
155 * std::cout << "Non-option #" << i << ": " << parse.nonOption(i) << "\n";
156 * }
157 * @endcode
158 *
159 * @par Option syntax:
160 * @li The Lean Mean C++ Option Parser follows POSIX <code>getopt()</code> conventions and supports
161 * GNU-style <code>getopt_long()</code> long options as well as Perl-style single-minus
162 * long options (<code>getopt_long_only()</code>).
163 * @li short options have the format @c -X where @c X is any character that fits in a char.
164 * @li short options can be grouped, i.e. <code>-X -Y</code> is equivalent to @c -XY.
165 * @li a short option may take an argument either separate (<code>-X foo</code>) or
166 * attached (@c -Xfoo). You can make the parser accept the additional format @c -X=foo by
167 * registering @c X as a long option (in addition to being a short option) and
168 * enabling single-minus long options.
169 * @li an argument-taking short option may be grouped if it is the last in the group, e.g.
170 * @c -ABCXfoo or <code> -ABCX foo </code> (@c foo is the argument to the @c -X option).
171 * @li a lone minus character @c '-' is not treated as an option. It is customarily used where
172 * a file name is expected to refer to stdin or stdout.
173 * @li long options have the format @c --option-name.
174 * @li the option-name of a long option can be anything and include any characters.
175 * Even @c = characters will work, but don't do that.
176 * @li [optional] long options may be abbreviated as long as the abbreviation is unambiguous.
177 * You can set a minimum length for abbreviations.
178 * @li [optional] long options may begin with a single minus. The double minus form is always
179 * accepted, too.
180 * @li a long option may take an argument either separate (<code> --option arg </code>) or
181 * attached (<code> --option=arg </code>). In the attached form the equals sign is mandatory.
182 * @li an empty string can be passed as an attached long option argument: <code> --option-name= </code>.
183 * Note the distinction between an empty string as argument and no argument at all.
184 * @li an empty string is permitted as separate argument to both long and short options.
185 * @li Arguments to both short and long options may start with a @c '-' character. E.g.
186 * <code> -X-X </code>, <code>-X -X</code> or <code> --long-X=-X </code>. If @c -X
187 * and @c --long-X take an argument, that argument will be @c "-X" in all 3 cases.
188 * @li If using the built-in @ref option::Arg::Optional "Arg::Optional", optional arguments must
189 * be attached.
190 * @li the special option @c -- (i.e. without a name) terminates the list of
191 * options. Everything that follows is a non-option argument, even if it starts with
192 * a @c '-' character. The @c -- itself will not appear in the parse results.
193 * @li the first argument that doesn't start with @c '-' or @c '--' and does not belong to
194 * a preceding argument-taking option, will terminate the option list and is the
195 * first non-option argument. All following command line arguments are treated as
196 * non-option arguments, even if they start with @c '-' . @n
197 * NOTE: This behaviour is mandated by POSIX, but GNU getopt() only honours this if it is
198 * explicitly requested (e.g. by setting POSIXLY_CORRECT). @n
199 * You can enable the GNU behaviour by passing @c true as first argument to
200 * e.g. @ref option::Parser::parse() "Parser::parse()".
201 * @li Arguments that look like options (i.e. @c '-' followed by at least 1 character) but
202 * aren't, are NOT treated as non-option arguments. They are treated as unknown options and
203 * are collected into a list of unknown options for error reporting. @n
204 * This means that in order to pass a first non-option
205 * argument beginning with the minus character it is required to use the
206 * @c -- special option, e.g.
207 * @code
208 * program -x -- --strange-filename
209 * @endcode
210 * In this example, @c --strange-filename is a non-option argument. If the @c --
211 * were omitted, it would be treated as an unknown option. @n
212 * See @ref option::Descriptor::longopt for information on how to collect unknown options.
213 *
214 */
215
216 #ifndef OPTIONPARSER_H_
217 #define OPTIONPARSER_H_
218
219 /** @brief The namespace of The Lean Mean C++ Option Parser. */
220 namespace option
221 {
222
223 #ifdef _MSC_VER
224 #include <intrin.h>
225 #pragma intrinsic(_BitScanReverse)
226 struct MSC_Builtin_CLZ
227 {
builtin_clzMSC_Builtin_CLZ228 static int builtin_clz(unsigned x)
229 {
230 unsigned long index;
231 _BitScanReverse(&index, x);
232 return 32-index; // int is always 32bit on Windows, even for target x64
233 }
234 };
235 #define __builtin_clz(x) MSC_Builtin_CLZ::builtin_clz(x)
236 #endif
237
238 class Option;
239
240 /**
241 * @brief Possible results when checking if an argument is valid for a certain option.
242 *
243 * In the case that no argument is provided for an option that takes an
244 * optional argument, return codes @c ARG_OK and @c ARG_IGNORE are equivalent.
245 */
246 enum ArgStatus
247 {
248 //! The option does not take an argument.
249 ARG_NONE,
250 //! The argument is acceptable for the option.
251 ARG_OK,
252 //! The argument is not acceptable but that's non-fatal because the option's argument is optional.
253 ARG_IGNORE,
254 //! The argument is not acceptable and that's fatal.
255 ARG_ILLEGAL
256 };
257
258 /**
259 * @brief Signature of functions that check if an argument is valid for a certain type of option.
260 *
261 * Every Option has such a function assigned in its Descriptor.
262 * @code
263 * Descriptor usage[] = { {UNKNOWN, 0, "", "", Arg::None, ""}, ... };
264 * @endcode
265 *
266 * A CheckArg function has the following signature:
267 * @code ArgStatus CheckArg(const Option& option, bool msg); @endcode
268 *
269 * It is used to check if a potential argument would be acceptable for the option.
270 * It will even be called if there is no argument. In that case @c option.arg will be @c NULL.
271 *
272 * If @c msg is @c true and the function determines that an argument is not acceptable and
273 * that this is a fatal error, it should output a message to the user before
274 * returning @ref ARG_ILLEGAL. If @c msg is @c false the function should remain silent (or you
275 * will get duplicate messages).
276 *
277 * See @ref ArgStatus for the meaning of the return values.
278 *
279 * While you can provide your own functions,
280 * often the following pre-defined checks (which never return @ref ARG_ILLEGAL) will suffice:
281 *
282 * @li @c Arg::None @copybrief Arg::None
283 * @li @c Arg::Optional @copybrief Arg::Optional
284 *
285 */
286 typedef ArgStatus (*CheckArg)(const Option& option, bool msg);
287
288 /**
289 * @brief Describes an option, its help text (usage) and how it should be parsed.
290 *
291 * The main input when constructing an option::Parser is an array of Descriptors.
292
293 * @par Example:
294 * @code
295 * enum OptionIndex {CREATE, ...};
296 * enum OptionType {DISABLE, ENABLE, OTHER};
297 *
298 * const option::Descriptor usage[] = {
299 * { CREATE, // index
300 * OTHER, // type
301 * "c", // shortopt
302 * "create", // longopt
303 * Arg::None, // check_arg
304 * "--create Tells the program to create something." // help
305 * }
306 * , ...
307 * };
308 * @endcode
309 */
310 struct Descriptor
311 {
312 /**
313 * @brief Index of this option's linked list in the array filled in by the parser.
314 *
315 * Command line options whose Descriptors have the same index will end up in the same
316 * linked list in the order in which they appear on the command line. If you have
317 * multiple long option aliases that refer to the same option, give their descriptors
318 * the same @c index.
319 *
320 * If you have options that mean exactly opposite things
321 * (e.g. @c --enable-foo and @c --disable-foo ), you should also give them the same
322 * @c index, but distinguish them through different values for @ref type.
323 * That way they end up in the same list and you can just take the last element of the
324 * list and use its type. This way you get the usual behaviour where switches later
325 * on the command line override earlier ones without having to code it manually.
326 *
327 * @par Tip:
328 * Use an enum rather than plain ints for better readability, as shown in the example
329 * at Descriptor.
330 */
331 const unsigned index;
332
333 /**
334 * @brief Used to distinguish between options with the same @ref index.
335 * See @ref index for details.
336 *
337 * It is recommended that you use an enum rather than a plain int to make your
338 * code more readable.
339 */
340 const int type;
341
342 /**
343 * @brief Each char in this string will be accepted as a short option character.
344 *
345 * The string must not include the minus character @c '-' or you'll get undefined
346 * behaviour.
347 *
348 * If this Descriptor should not have short option characters, use the empty
349 * string "". NULL is not permitted here!
350 *
351 * See @ref longopt for more information.
352 */
353 const char* const shortopt;
354
355 /**
356 * @brief The long option name (without the leading @c -- ).
357 *
358 * If this Descriptor should not have a long option name, use the empty
359 * string "". NULL is not permitted here!
360 *
361 * While @ref shortopt allows multiple short option characters, each
362 * Descriptor can have only a single long option name. If you have multiple
363 * long option names referring to the same option use separate Descriptors
364 * that have the same @ref index and @ref type. You may repeat
365 * short option characters in such an alias Descriptor but there's no need to.
366 *
367 * @par Dummy Descriptors:
368 * You can use dummy Descriptors with an
369 * empty string for both @ref shortopt and @ref longopt to add text to
370 * the usage that is not related to a specific option. See @ref help.
371 * The first dummy Descriptor will be used for unknown options (see below).
372 *
373 * @par Unknown Option Descriptor:
374 * The first dummy Descriptor in the list of Descriptors,
375 * whose @ref shortopt and @ref longopt are both the empty string, will be used
376 * as the Descriptor for unknown options. An unknown option is a string in
377 * the argument vector that is not a lone minus @c '-' but starts with a minus
378 * character and does not match any Descriptor's @ref shortopt or @ref longopt. @n
379 * Note that the dummy descriptor's @ref check_arg function @e will be called and
380 * its return value will be evaluated as usual. I.e. if it returns @ref ARG_ILLEGAL
381 * the parsing will be aborted with <code>Parser::error()==true</code>. @n
382 * if @c check_arg does not return @ref ARG_ILLEGAL the descriptor's
383 * @ref index @e will be used to pick the linked list into which
384 * to put the unknown option. @n
385 * If there is no dummy descriptor, unknown options will be dropped silently.
386 *
387 */
388 const char* const longopt;
389
390 /**
391 * @brief For each option that matches @ref shortopt or @ref longopt this function
392 * will be called to check a potential argument to the option.
393 *
394 * This function will be called even if there is no potential argument. In that case
395 * it will be passed @c NULL as @c arg parameter. Do not confuse this with the empty
396 * string.
397 *
398 * See @ref CheckArg for more information.
399 */
400 const CheckArg check_arg;
401
402 /**
403 * @brief The usage text associated with the options in this Descriptor.
404 *
405 * You can use option::printUsage() to format your usage message based on
406 * the @c help texts. You can use dummy Descriptors where
407 * @ref shortopt and @ref longopt are both the empty string to add text to
408 * the usage that is not related to a specific option.
409 *
410 * See option::printUsage() for special formatting characters you can use in
411 * @c help to get a column layout.
412 *
413 * @attention
414 * Must be UTF-8-encoded. If your compiler supports C++11 you can use the "u8"
415 * prefix to make sure string literals are properly encoded.
416 */
417 const char* help;
418 };
419
420 /**
421 * @brief A parsed option from the command line together with its argument if it has one.
422 *
423 * The Parser chains all parsed options with the same Descriptor::index together
424 * to form a linked list. This allows you to easily implement all of the common ways
425 * of handling repeated options and enable/disable pairs.
426 *
427 * @li Test for presence of a switch in the argument vector:
428 * @code if ( options[QUIET] ) ... @endcode
429 * @li Evaluate --enable-foo/--disable-foo pair where the last one used wins:
430 * @code if ( options[FOO].last()->type() == DISABLE ) ... @endcode
431 * @li Cumulative option (-v verbose, -vv more verbose, -vvv even more verbose):
432 * @code int verbosity = options[VERBOSE].count(); @endcode
433 * @li Iterate over all --file=<fname> arguments:
434 * @code for (Option* opt = options[FILE]; opt; opt = opt->next())
435 * fname = opt->arg; ... @endcode
436 */
437 class Option
438 {
439 Option* next_;
440 Option* prev_;
441 public:
442 /**
443 * @brief Pointer to this Option's Descriptor.
444 *
445 * Remember that the first dummy descriptor (see @ref Descriptor::longopt) is used
446 * for unknown options.
447 *
448 * @attention
449 * @c desc==NULL signals that this Option is unused. This is the default state of
450 * elements in the result array. You don't need to test @c desc explicitly. You
451 * can simply write something like this:
452 * @code
453 * if (options[CREATE])
454 * {
455 * ...
456 * }
457 * @endcode
458 * This works because of <code> operator const Option*() </code>.
459 */
460 const Descriptor* desc;
461
462 /**
463 * @brief The name of the option as used on the command line.
464 *
465 * The main purpose of this string is to be presented to the user in messages.
466 *
467 * In the case of a long option, this is the actual @c argv pointer, i.e. the first
468 * character is a '-'. In the case of a short option this points to the option
469 * character within the @c argv string.
470 *
471 * Note that in the case of a short option group or an attached option argument, this
472 * string will contain additional characters following the actual name. Use @ref namelen
473 * to filter out the actual option name only.
474 *
475 */
476 const char* name;
477
478 /**
479 * @brief Pointer to this Option's argument (if any).
480 *
481 * NULL if this option has no argument. Do not confuse this with the empty string which
482 * is a valid argument.
483 */
484 const char* arg;
485
486 /**
487 * @brief The length of the option @ref name.
488 *
489 * Because @ref name points into the actual @c argv string, the option name may be
490 * followed by more characters (e.g. other short options in the same short option group).
491 * This value is the number of bytes (not characters!) that are part of the actual name.
492 *
493 * For a short option, this length is always 1. For a long option this length is always
494 * at least 2 if single minus long options are permitted and at least 3 if they are disabled.
495 *
496 * @note
497 * In the pathological case of a minus within a short option group (e.g. @c -xf-z), this
498 * length is incorrect, because this case will be misinterpreted as a long option and the
499 * name will therefore extend to the string's 0-terminator or a following '=" character
500 * if there is one. This is irrelevant for most uses of @ref name and @c namelen. If you
501 * really need to distinguish the case of a long and a short option, compare @ref name to
502 * the @c argv pointers. A long option's @c name is always identical to one of them,
503 * whereas a short option's is never.
504 */
505 int namelen;
506
507 /**
508 * @brief Returns Descriptor::type of this Option's Descriptor, or 0 if this Option
509 * is invalid (unused).
510 *
511 * Because this method (and last(), too) can be used even on unused Options with desc==0, you can (provided
512 * you arrange your types properly) switch on type() without testing validity first.
513 * @code
514 * enum OptionType { UNUSED=0, DISABLED=0, ENABLED=1 };
515 * enum OptionIndex { FOO };
516 * const Descriptor usage[] = {
517 * { FOO, ENABLED, "", "enable-foo", Arg::None, 0 },
518 * { FOO, DISABLED, "", "disable-foo", Arg::None, 0 },
519 * { 0, 0, 0, 0, 0, 0 } };
520 * ...
521 * switch(options[FOO].last()->type()) // no validity check required!
522 * {
523 * case ENABLED: ...
524 * case DISABLED: ... // UNUSED==DISABLED !
525 * }
526 * @endcode
527 */
type()528 int type() const
529 {
530 return desc == 0 ? 0 : desc->type;
531 }
532
533 /**
534 * @brief Returns Descriptor::index of this Option's Descriptor, or -1 if this Option
535 * is invalid (unused).
536 */
index()537 int index() const
538 {
539 return desc == 0 ? -1 : (int)desc->index;
540 }
541
542 /**
543 * @brief Returns the number of times this Option (or others with the same Descriptor::index)
544 * occurs in the argument vector.
545 *
546 * This corresponds to the number of elements in the linked list this Option is part of.
547 * It doesn't matter on which element you call count(). The return value is always the same.
548 *
549 * Use this to implement cumulative options, such as -v, -vv, -vvv for
550 * different verbosity levels.
551 *
552 * Returns 0 when called for an unused/invalid option.
553 */
count()554 int count()
555 {
556 int c = (desc == 0 ? 0 : 1);
557 Option* p = first();
558 while (!p->isLast())
559 {
560 ++c;
561 p = p->next_;
562 };
563 return c;
564 }
565
566 /**
567 * @brief Returns true iff this is the first element of the linked list.
568 *
569 * The first element in the linked list is the first option on the command line
570 * that has the respective Descriptor::index value.
571 *
572 * Returns true for an unused/invalid option.
573 */
isFirst()574 bool isFirst() const
575 {
576 return isTagged(prev_);
577 }
578
579 /**
580 * @brief Returns true iff this is the last element of the linked list.
581 *
582 * The last element in the linked list is the last option on the command line
583 * that has the respective Descriptor::index value.
584 *
585 * Returns true for an unused/invalid option.
586 */
isLast()587 bool isLast() const
588 {
589 return isTagged(next_);
590 }
591
592 /**
593 * @brief Returns a pointer to the first element of the linked list.
594 *
595 * Use this when you want the first occurrence of an option on the command line to
596 * take precedence. Note that this is not the way most programs handle options.
597 * You should probably be using last() instead.
598 *
599 * @note
600 * This method may be called on an unused/invalid option and will return a pointer to the
601 * option itself.
602 */
first()603 Option* first()
604 {
605 Option* p = this;
606 while (!p->isFirst())
607 p = p->prev_;
608 return p;
609 }
610
611 /**
612 * @brief Returns a pointer to the last element of the linked list.
613 *
614 * Use this when you want the last occurrence of an option on the command line to
615 * take precedence. This is the most common way of handling conflicting options.
616 *
617 * @note
618 * This method may be called on an unused/invalid option and will return a pointer to the
619 * option itself.
620 *
621 * @par Tip:
622 * If you have options with opposite meanings (e.g. @c --enable-foo and @c --disable-foo), you
623 * can assign them the same Descriptor::index to get them into the same list. Distinguish them by
624 * Descriptor::type and all you have to do is check <code> last()->type() </code> to get
625 * the state listed last on the command line.
626 */
last()627 Option* last()
628 {
629 return first()->prevwrap();
630 }
631
632 /**
633 * @brief Returns a pointer to the previous element of the linked list or NULL if
634 * called on first().
635 *
636 * If called on first() this method returns NULL. Otherwise it will return the
637 * option with the same Descriptor::index that precedes this option on the command
638 * line.
639 */
prev()640 Option* prev()
641 {
642 return isFirst() ? 0 : prev_;
643 }
644
645 /**
646 * @brief Returns a pointer to the previous element of the linked list with wrap-around from
647 * first() to last().
648 *
649 * If called on first() this method returns last(). Otherwise it will return the
650 * option with the same Descriptor::index that precedes this option on the command
651 * line.
652 */
prevwrap()653 Option* prevwrap()
654 {
655 return untag(prev_);
656 }
657
658 /**
659 * @brief Returns a pointer to the next element of the linked list or NULL if called
660 * on last().
661 *
662 * If called on last() this method returns NULL. Otherwise it will return the
663 * option with the same Descriptor::index that follows this option on the command
664 * line.
665 */
next()666 Option* next()
667 {
668 return isLast() ? 0 : next_;
669 }
670
671 /**
672 * @brief Returns a pointer to the next element of the linked list with wrap-around from
673 * last() to first().
674 *
675 * If called on last() this method returns first(). Otherwise it will return the
676 * option with the same Descriptor::index that follows this option on the command
677 * line.
678 */
nextwrap()679 Option* nextwrap()
680 {
681 return untag(next_);
682 }
683
684 /**
685 * @brief Makes @c new_last the new last() by chaining it into the list after last().
686 *
687 * It doesn't matter which element you call append() on. The new element will always
688 * be appended to last().
689 *
690 * @attention
691 * @c new_last must not yet be part of a list, or that list will become corrupted, because
692 * this method does not unchain @c new_last from an existing list.
693 */
append(Option * new_last)694 void append(Option* new_last)
695 {
696 Option* p = last();
697 Option* f = first();
698 p->next_ = new_last;
699 new_last->prev_ = p;
700 new_last->next_ = tag(f);
701 f->prev_ = tag(new_last);
702 }
703
704 /**
705 * @brief Casts from Option to const Option* but only if this Option is valid.
706 *
707 * If this Option is valid (i.e. @c desc!=NULL), returns this.
708 * Otherwise returns NULL. This allows testing an Option directly
709 * in an if-clause to see if it is used:
710 * @code
711 * if (options[CREATE])
712 * {
713 * ...
714 * }
715 * @endcode
716 * It also allows you to write loops like this:
717 * @code for (Option* opt = options[FILE]; opt; opt = opt->next())
718 * fname = opt->arg; ... @endcode
719 */
720 operator const Option*() const
721 {
722 return desc ? this : 0;
723 }
724
725 /**
726 * @brief Casts from Option to Option* but only if this Option is valid.
727 *
728 * If this Option is valid (i.e. @c desc!=NULL), returns this.
729 * Otherwise returns NULL. This allows testing an Option directly
730 * in an if-clause to see if it is used:
731 * @code
732 * if (options[CREATE])
733 * {
734 * ...
735 * }
736 * @endcode
737 * It also allows you to write loops like this:
738 * @code for (Option* opt = options[FILE]; opt; opt = opt->next())
739 * fname = opt->arg; ... @endcode
740 */
741 operator Option*()
742 {
743 return desc ? this : 0;
744 }
745
746 /**
747 * @brief Creates a new Option that is a one-element linked list and has NULL
748 * @ref desc, @ref name, @ref arg and @ref namelen.
749 */
Option()750 Option() :
751 desc(0), name(0), arg(0), namelen(0)
752 {
753 prev_ = tag(this);
754 next_ = tag(this);
755 }
756
757 /**
758 * @brief Creates a new Option that is a one-element linked list and has the given
759 * values for @ref desc, @ref name and @ref arg.
760 *
761 * If @c name_ points at a character other than '-' it will be assumed to refer to a
762 * short option and @ref namelen will be set to 1. Otherwise the length will extend to
763 * the first '=' character or the string's 0-terminator.
764 */
Option(const Descriptor * desc_,const char * name_,const char * arg_)765 Option(const Descriptor* desc_, const char* name_, const char* arg_)
766 {
767 init(desc_, name_, arg_);
768 }
769
770 /**
771 * @brief Makes @c *this a copy of @c orig except for the linked list pointers.
772 *
773 * After this operation @c *this will be a one-element linked list.
774 */
775 void operator=(const Option& orig)
776 {
777 init(orig.desc, orig.name, orig.arg);
778 }
779
780 /**
781 * @brief Makes @c *this a copy of @c orig except for the linked list pointers.
782 *
783 * After this operation @c *this will be a one-element linked list.
784 */
Option(const Option & orig)785 Option(const Option& orig)
786 {
787 init(orig.desc, orig.name, orig.arg);
788 }
789
790 private:
791 /**
792 * @internal
793 * @brief Sets the fields of this Option to the given values (extracting @c name if necessary).
794 *
795 * If @c name_ points at a character other than '-' it will be assumed to refer to a
796 * short option and @ref namelen will be set to 1. Otherwise the length will extend to
797 * the first '=' character or the string's 0-terminator.
798 */
init(const Descriptor * desc_,const char * name_,const char * arg_)799 void init(const Descriptor* desc_, const char* name_, const char* arg_)
800 {
801 desc = desc_;
802 name = name_;
803 arg = arg_;
804 prev_ = tag(this);
805 next_ = tag(this);
806 namelen = 0;
807 if (name == 0)
808 return;
809 namelen = 1;
810 if (name[0] != '-')
811 return;
812 while (name[namelen] != 0 && name[namelen] != '=')
813 ++namelen;
814 }
815
tag(Option * ptr)816 static Option* tag(Option* ptr)
817 {
818 return (Option*) ((unsigned long long) ptr | 1);
819 }
820
untag(Option * ptr)821 static Option* untag(Option* ptr)
822 {
823 return (Option*) ((unsigned long long) ptr & ~1ull);
824 }
825
isTagged(Option * ptr)826 static bool isTagged(Option* ptr)
827 {
828 return ((unsigned long long) ptr & 1);
829 }
830 };
831
832 /**
833 * @brief Functions for checking the validity of option arguments.
834 *
835 * @copydetails CheckArg
836 *
837 * The following example code
838 * can serve as starting place for writing your own more complex CheckArg functions:
839 * @code
840 * struct Arg: public option::Arg
841 * {
842 * static void printError(const char* msg1, const option::Option& opt, const char* msg2)
843 * {
844 * fprintf(stderr, "ERROR: %s", msg1);
845 * fwrite(opt.name, opt.namelen, 1, stderr);
846 * fprintf(stderr, "%s", msg2);
847 * }
848 *
849 * static option::ArgStatus Unknown(const option::Option& option, bool msg)
850 * {
851 * if (msg) printError("Unknown option '", option, "'\n");
852 * return option::ARG_ILLEGAL;
853 * }
854 *
855 * static option::ArgStatus Required(const option::Option& option, bool msg)
856 * {
857 * if (option.arg != 0)
858 * return option::ARG_OK;
859 *
860 * if (msg) printError("Option '", option, "' requires an argument\n");
861 * return option::ARG_ILLEGAL;
862 * }
863 *
864 * static option::ArgStatus NonEmpty(const option::Option& option, bool msg)
865 * {
866 * if (option.arg != 0 && option.arg[0] != 0)
867 * return option::ARG_OK;
868 *
869 * if (msg) printError("Option '", option, "' requires a non-empty argument\n");
870 * return option::ARG_ILLEGAL;
871 * }
872 *
873 * static option::ArgStatus Numeric(const option::Option& option, bool msg)
874 * {
875 * char* endptr = 0;
876 * if (option.arg != 0 && strtol(option.arg, &endptr, 10)){};
877 * if (endptr != option.arg && *endptr == 0)
878 * return option::ARG_OK;
879 *
880 * if (msg) printError("Option '", option, "' requires a numeric argument\n");
881 * return option::ARG_ILLEGAL;
882 * }
883 * };
884 * @endcode
885 */
886 struct Arg
887 {
888 //! @brief For options that don't take an argument: Returns ARG_NONE.
NoneArg889 static ArgStatus None(const Option&, bool)
890 {
891 return ARG_NONE;
892 }
893
894 //! @brief Returns ARG_OK if the argument is attached and ARG_IGNORE otherwise.
OptionalArg895 static ArgStatus Optional(const Option& option, bool)
896 {
897 if (option.arg && option.name[option.namelen] != 0)
898 return ARG_OK;
899 else
900 return ARG_IGNORE;
901 }
902 };
903
904 /**
905 * @brief Determines the minimum lengths of the buffer and options arrays used for Parser.
906 *
907 * Because Parser doesn't use dynamic memory its output arrays have to be pre-allocated.
908 * If you don't want to use fixed size arrays (which may turn out too small, causing
909 * command line arguments to be dropped), you can use Stats to determine the correct sizes.
910 * Stats work cumulative. You can first pass in your default options and then the real
911 * options and afterwards the counts will reflect the union.
912 */
913 struct Stats
914 {
915 /**
916 * @brief Number of elements needed for a @c buffer[] array to be used for
917 * @ref Parser::parse() "parsing" the same argument vectors that were fed
918 * into this Stats object.
919 *
920 * @note
921 * This number is always 1 greater than the actual number needed, to give
922 * you a sentinel element.
923 */
924 unsigned buffer_max;
925
926 /**
927 * @brief Number of elements needed for an @c options[] array to be used for
928 * @ref Parser::parse() "parsing" the same argument vectors that were fed
929 * into this Stats object.
930 *
931 * @note
932 * @li This number is always 1 greater than the actual number needed, to give
933 * you a sentinel element.
934 * @li This number depends only on the @c usage, not the argument vectors, because
935 * the @c options array needs exactly one slot for each possible Descriptor::index.
936 */
937 unsigned options_max;
938
939 /**
940 * @brief Creates a Stats object with counts set to 1 (for the sentinel element).
941 */
StatsStats942 Stats() :
943 buffer_max(1), options_max(1) // 1 more than necessary as sentinel
944 {
945 }
946
947 /**
948 * @brief Creates a new Stats object and immediately updates it for the
949 * given @c usage and argument vector. You may pass 0 for @c argc and/or @c argv,
950 * if you just want to update @ref options_max.
951 *
952 * @note
953 * The calls to Stats methods must match the later calls to Parser methods.
954 * See Parser::parse() for the meaning of the arguments.
955 */
956 Stats(bool gnu, const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, //
957 bool single_minus_longopt = false) :
958 buffer_max(1), options_max(1) // 1 more than necessary as sentinel
959 {
960 add(gnu, usage, argc, argv, min_abbr_len, single_minus_longopt);
961 }
962
963 //! @brief Stats(...) with non-const argv.
964 Stats(bool gnu, const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, //
965 bool single_minus_longopt = false) :
966 buffer_max(1), options_max(1) // 1 more than necessary as sentinel
967 {
968 add(gnu, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt);
969 }
970
971 //! @brief POSIX Stats(...) (gnu==false).
972 Stats(const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, //
973 bool single_minus_longopt = false) :
974 buffer_max(1), options_max(1) // 1 more than necessary as sentinel
975 {
976 add(false, usage, argc, argv, min_abbr_len, single_minus_longopt);
977 }
978
979 //! @brief POSIX Stats(...) (gnu==false) with non-const argv.
980 Stats(const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, //
981 bool single_minus_longopt = false) :
982 buffer_max(1), options_max(1) // 1 more than necessary as sentinel
983 {
984 add(false, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt);
985 }
986
987 /**
988 * @brief Updates this Stats object for the
989 * given @c usage and argument vector. You may pass 0 for @c argc and/or @c argv,
990 * if you just want to update @ref options_max.
991 *
992 * @note
993 * The calls to Stats methods must match the later calls to Parser methods.
994 * See Parser::parse() for the meaning of the arguments.
995 */
996 void add(bool gnu, const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, //
997 bool single_minus_longopt = false);
998
999 //! @brief add() with non-const argv.
1000 void add(bool gnu, const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, //
1001 bool single_minus_longopt = false)
1002 {
1003 add(gnu, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt);
1004 }
1005
1006 //! @brief POSIX add() (gnu==false).
1007 void add(const Descriptor usage[], int argc, const char** argv, int min_abbr_len = 0, //
1008 bool single_minus_longopt = false)
1009 {
1010 add(false, usage, argc, argv, min_abbr_len, single_minus_longopt);
1011 }
1012
1013 //! @brief POSIX add() (gnu==false) with non-const argv.
1014 void add(const Descriptor usage[], int argc, char** argv, int min_abbr_len = 0, //
1015 bool single_minus_longopt = false)
1016 {
1017 add(false, usage, argc, (const char**) argv, min_abbr_len, single_minus_longopt);
1018 }
1019 private:
1020 class CountOptionsAction;
1021 };
1022
1023 /**
1024 * @brief Checks argument vectors for validity and parses them into data
1025 * structures that are easier to work with.
1026 *
1027 * @par Example:
1028 * @code
1029 * int main(int argc, char* argv[])
1030 * {
1031 * argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present
1032 * option::Stats stats(usage, argc, argv);
1033 * option::Option options[stats.options_max], buffer[stats.buffer_max];
1034 * option::Parser parse(usage, argc, argv, options, buffer);
1035 *
1036 * if (parse.error())
1037 * return 1;
1038 *
1039 * if (options[HELP])
1040 * ...
1041 * @endcode
1042 */
1043 class Parser
1044 {
1045 int op_count; //!< @internal @brief see optionsCount()
1046 int nonop_count; //!< @internal @brief see nonOptionsCount()
1047 const char** nonop_args; //!< @internal @brief see nonOptions()
1048 bool err; //!< @internal @brief see error()
1049 public:
1050
1051 /**
1052 * @brief Creates a new Parser.
1053 */
Parser()1054 Parser() :
1055 op_count(0), nonop_count(0), nonop_args(0), err(false)
1056 {
1057 }
1058
1059 /**
1060 * @brief Creates a new Parser and immediately parses the given argument vector.
1061 * @copydetails parse()
1062 */
1063 Parser(bool gnu, const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[],
1064 int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1) :
1065 op_count(0), nonop_count(0), nonop_args(0), err(false)
1066 {
1067 parse(gnu, usage, argc, argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
1068 }
1069
1070 //! @brief Parser(...) with non-const argv.
1071 Parser(bool gnu, const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[],
1072 int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1) :
1073 op_count(0), nonop_count(0), nonop_args(0), err(false)
1074 {
1075 parse(gnu, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
1076 }
1077
1078 //! @brief POSIX Parser(...) (gnu==false).
1079 Parser(const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[], int min_abbr_len = 0,
1080 bool single_minus_longopt = false, int bufmax = -1) :
1081 op_count(0), nonop_count(0), nonop_args(0), err(false)
1082 {
1083 parse(false, usage, argc, argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
1084 }
1085
1086 //! @brief POSIX Parser(...) (gnu==false) with non-const argv.
1087 Parser(const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[], int min_abbr_len = 0,
1088 bool single_minus_longopt = false, int bufmax = -1) :
1089 op_count(0), nonop_count(0), nonop_args(0), err(false)
1090 {
1091 parse(false, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
1092 }
1093
1094 /**
1095 * @brief Parses the given argument vector.
1096 *
1097 * @param gnu if true, parse() will not stop at the first non-option argument. Instead it will
1098 * reorder arguments so that all non-options are at the end. This is the default behaviour
1099 * of GNU getopt() but is not conforming to POSIX. @n
1100 * Note, that once the argument vector has been reordered, the @c gnu flag will have
1101 * no further effect on this argument vector. So it is enough to pass @c gnu==true when
1102 * creating Stats.
1103 * @param usage Array of Descriptor objects that describe the options to support. The last entry
1104 * of this array must have 0 in all fields.
1105 * @param argc The number of elements from @c argv that are to be parsed. If you pass -1, the number
1106 * will be determined automatically. In that case the @c argv list must end with a NULL
1107 * pointer.
1108 * @param argv The arguments to be parsed. If you pass -1 as @c argc the last pointer in the @c argv
1109 * list must be NULL to mark the end.
1110 * @param options Each entry is the first element of a linked list of Options. Each new option
1111 * that is parsed will be appended to the list specified by that Option's
1112 * Descriptor::index. If an entry is not yet used (i.e. the Option is invalid),
1113 * it will be replaced rather than appended to. @n
1114 * The minimum length of this array is the greatest Descriptor::index value that
1115 * occurs in @c usage @e PLUS ONE.
1116 * @param buffer Each argument that is successfully parsed (including unknown arguments, if they
1117 * have a Descriptor whose CheckArg does not return @ref ARG_ILLEGAL) will be stored in this
1118 * array. parse() scans the array for the first invalid entry and begins writing at that
1119 * index. You can pass @c bufmax to limit the number of options stored.
1120 * @param min_abbr_len Passing a value <code> min_abbr_len > 0 </code> enables abbreviated long
1121 * options. The parser will match a prefix of a long option as if it was
1122 * the full long option (e.g. @c --foob=10 will be interpreted as if it was
1123 * @c --foobar=10 ), as long as the prefix has at least @c min_abbr_len characters
1124 * (not counting the @c -- ) and is unambiguous.
1125 * @n Be careful if combining @c min_abbr_len=1 with @c single_minus_longopt=true
1126 * because the ambiguity check does not consider short options and abbreviated
1127 * single minus long options will take precedence over short options.
1128 * @param single_minus_longopt Passing @c true for this option allows long options to begin with
1129 * a single minus. The double minus form will still be recognized. Note that
1130 * single minus long options take precedence over short options and short option
1131 * groups. E.g. @c -file would be interpreted as @c --file and not as
1132 * <code> -f -i -l -e </code> (assuming a long option named @c "file" exists).
1133 * @param bufmax The greatest index in the @c buffer[] array that parse() will write to is
1134 * @c bufmax-1. If there are more options, they will be processed (in particular
1135 * their CheckArg will be called) but not stored. @n
1136 * If you used Stats::buffer_max to dimension this array, you can pass
1137 * -1 (or not pass @c bufmax at all) which tells parse() that the buffer is
1138 * "large enough".
1139 * @attention
1140 * Remember that @c options and @c buffer store Option @e objects, not pointers. Therefore it
1141 * is not possible for the same object to be in both arrays. For those options that are found in
1142 * both @c buffer[] and @c options[] the respective objects are independent copies. And only the
1143 * objects in @c options[] are properly linked via Option::next() and Option::prev().
1144 * You can iterate over @c buffer[] to
1145 * process all options in the order they appear in the argument vector, but if you want access to
1146 * the other Options with the same Descriptor::index, then you @e must access the linked list via
1147 * @c options[]. You can get the linked list in options from a buffer object via something like
1148 * @c options[buffer[i].index()].
1149 */
1150 void parse(bool gnu, const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[],
1151 int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1);
1152
1153 //! @brief parse() with non-const argv.
1154 void parse(bool gnu, const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[],
1155 int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1)
1156 {
1157 parse(gnu, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
1158 }
1159
1160 //! @brief POSIX parse() (gnu==false).
1161 void parse(const Descriptor usage[], int argc, const char** argv, Option options[], Option buffer[],
1162 int min_abbr_len = 0, bool single_minus_longopt = false, int bufmax = -1)
1163 {
1164 parse(false, usage, argc, argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
1165 }
1166
1167 //! @brief POSIX parse() (gnu==false) with non-const argv.
1168 void parse(const Descriptor usage[], int argc, char** argv, Option options[], Option buffer[], int min_abbr_len = 0,
1169 bool single_minus_longopt = false, int bufmax = -1)
1170 {
1171 parse(false, usage, argc, (const char**) argv, options, buffer, min_abbr_len, single_minus_longopt, bufmax);
1172 }
1173
1174 /**
1175 * @brief Returns the number of valid Option objects in @c buffer[].
1176 *
1177 * @note
1178 * @li The returned value always reflects the number of Options in the buffer[] array used for
1179 * the most recent call to parse().
1180 * @li The count (and the buffer[]) includes unknown options if they are collected
1181 * (see Descriptor::longopt).
1182 */
optionsCount()1183 int optionsCount()
1184 {
1185 return op_count;
1186 }
1187
1188 /**
1189 * @brief Returns the number of non-option arguments that remained at the end of the
1190 * most recent parse() that actually encountered non-option arguments.
1191 *
1192 * @note
1193 * A parse() that does not encounter non-option arguments will leave this value
1194 * as well as nonOptions() undisturbed. This means you can feed the Parser a
1195 * default argument vector that contains non-option arguments (e.g. a default filename).
1196 * Then you feed it the actual arguments from the user. If the user has supplied at
1197 * least one non-option argument, all of the non-option arguments from the default
1198 * disappear and are replaced by the user's non-option arguments. However, if the
1199 * user does not supply any non-option arguments the defaults will still be in
1200 * effect.
1201 */
nonOptionsCount()1202 int nonOptionsCount()
1203 {
1204 return nonop_count;
1205 }
1206
1207 /**
1208 * @brief Returns a pointer to an array of non-option arguments (only valid
1209 * if <code>nonOptionsCount() >0 </code>).
1210 *
1211 * @note
1212 * @li parse() does not copy arguments, so this pointer points into the actual argument
1213 * vector as passed to parse().
1214 * @li As explained at nonOptionsCount() this pointer is only changed by parse() calls
1215 * that actually encounter non-option arguments. A parse() call that encounters only
1216 * options, will not change nonOptions().
1217 */
nonOptions()1218 const char** nonOptions()
1219 {
1220 return nonop_args;
1221 }
1222
1223 /**
1224 * @brief Returns <b><code>nonOptions()[i]</code></b> (@e without checking if i is in range!).
1225 */
nonOption(int i)1226 const char* nonOption(int i)
1227 {
1228 return nonOptions()[i];
1229 }
1230
1231 /**
1232 * @brief Returns @c true if an unrecoverable error occurred while parsing options.
1233 *
1234 * An illegal argument to an option (i.e. CheckArg returns @ref ARG_ILLEGAL) is an
1235 * unrecoverable error that aborts the parse. Unknown options are only an error if
1236 * their CheckArg function returns @ref ARG_ILLEGAL. Otherwise they are collected.
1237 * In that case if you want to exit the program if either an illegal argument
1238 * or an unknown option has been passed, use code like this
1239 *
1240 * @code
1241 * if (parser.error() || options[UNKNOWN])
1242 * exit(1);
1243 * @endcode
1244 *
1245 */
error()1246 bool error()
1247 {
1248 return err;
1249 }
1250
1251 private:
1252 friend struct Stats;
1253 class StoreOptionAction;
1254 struct Action;
1255
1256 /**
1257 * @internal
1258 * @brief This is the core function that does all the parsing.
1259 * @retval false iff an unrecoverable error occurred.
1260 */
1261 static bool workhorse(bool gnu, const Descriptor usage[], int numargs, const char** args, Action& action,
1262 bool single_minus_longopt, bool print_errors, int min_abbr_len);
1263
1264 /**
1265 * @internal
1266 * @brief Returns true iff @c st1 is a prefix of @c st2 and
1267 * in case @c st2 is longer than @c st1, then
1268 * the first additional character is '='.
1269 *
1270 * @par Examples:
1271 * @code
1272 * streq("foo", "foo=bar") == true
1273 * streq("foo", "foobar") == false
1274 * streq("foo", "foo") == true
1275 * streq("foo=bar", "foo") == false
1276 * @endcode
1277 */
streq(const char * st1,const char * st2)1278 static bool streq(const char* st1, const char* st2)
1279 {
1280 while (*st1 != 0)
1281 if (*st1++ != *st2++)
1282 return false;
1283 return (*st2 == 0 || *st2 == '=');
1284 }
1285
1286 /**
1287 * @internal
1288 * @brief Like streq() but handles abbreviations.
1289 *
1290 * Returns true iff @c st1 and @c st2 have a common
1291 * prefix with the following properties:
1292 * @li (if min > 0) its length is at least @c min characters or the same length as @c st1 (whichever is smaller).
1293 * @li (if min <= 0) its length is the same as that of @c st1
1294 * @li within @c st2 the character following the common prefix is either '=' or end-of-string.
1295 *
1296 * Examples:
1297 * @code
1298 * streqabbr("foo", "foo=bar",<anything>) == true
1299 * streqabbr("foo", "fo=bar" , 2) == true
1300 * streqabbr("foo", "fo" , 2) == true
1301 * streqabbr("foo", "fo" , 0) == false
1302 * streqabbr("foo", "f=bar" , 2) == false
1303 * streqabbr("foo", "f" , 2) == false
1304 * streqabbr("fo" , "foo=bar",<anything>) == false
1305 * streqabbr("foo", "foobar" ,<anything>) == false
1306 * streqabbr("foo", "fobar" ,<anything>) == false
1307 * streqabbr("foo", "foo" ,<anything>) == true
1308 * @endcode
1309 */
streqabbr(const char * st1,const char * st2,long long min)1310 static bool streqabbr(const char* st1, const char* st2, long long min)
1311 {
1312 const char* st1start = st1;
1313 while (*st1 != 0 && (*st1 == *st2))
1314 {
1315 ++st1;
1316 ++st2;
1317 }
1318
1319 return (*st1 == 0 || (min > 0 && (st1 - st1start) >= min)) && (*st2 == 0 || *st2 == '=');
1320 }
1321
1322 /**
1323 * @internal
1324 * @brief Returns true iff character @c ch is contained in the string @c st.
1325 *
1326 * Returns @c true for @c ch==0 .
1327 */
instr(char ch,const char * st)1328 static bool instr(char ch, const char* st)
1329 {
1330 while (*st != 0 && *st != ch)
1331 ++st;
1332 return *st == ch;
1333 }
1334
1335 /**
1336 * @internal
1337 * @brief Rotates <code>args[-count],...,args[-1],args[0]</code> to become
1338 * <code>args[0],args[-count],...,args[-1]</code>.
1339 */
shift(const char ** args,int count)1340 static void shift(const char** args, int count)
1341 {
1342 for (int i = 0; i > -count; --i)
1343 {
1344 const char* temp = args[i];
1345 args[i] = args[i - 1];
1346 args[i - 1] = temp;
1347 }
1348 }
1349 };
1350
1351 /**
1352 * @internal
1353 * @brief Interface for actions Parser::workhorse() should perform for each Option it
1354 * parses.
1355 */
1356 struct Parser::Action
1357 {
1358 /**
1359 * @brief Called by Parser::workhorse() for each Option that has been successfully
1360 * parsed (including unknown
1361 * options if they have a Descriptor whose Descriptor::check_arg does not return
1362 * @ref ARG_ILLEGAL.
1363 *
1364 * Returns @c false iff a fatal error has occured and the parse should be aborted.
1365 */
performAction1366 virtual bool perform(Option&)
1367 {
1368 return true;
1369 }
1370
1371 /**
1372 * @brief Called by Parser::workhorse() after finishing the parse.
1373 * @param numargs the number of non-option arguments remaining
1374 * @param args pointer to the first remaining non-option argument (if numargs > 0).
1375 *
1376 * @return
1377 * @c false iff a fatal error has occurred.
1378 */
finishedAction1379 virtual bool finished(int numargs, const char** args)
1380 {
1381 (void) numargs;
1382 (void) args;
1383 return true;
1384 }
1385 };
1386
1387 /**
1388 * @internal
1389 * @brief An Action to pass to Parser::workhorse() that will increment a counter for
1390 * each parsed Option.
1391 */
1392 class Stats::CountOptionsAction: public Parser::Action
1393 {
1394 unsigned* buffer_max;
1395 public:
1396 /**
1397 * Creates a new CountOptionsAction that will increase @c *buffer_max_ for each
1398 * parsed Option.
1399 */
CountOptionsAction(unsigned * buffer_max_)1400 CountOptionsAction(unsigned* buffer_max_) :
1401 buffer_max(buffer_max_)
1402 {
1403 }
1404
perform(Option &)1405 bool perform(Option&)
1406 {
1407 if (*buffer_max == 0x7fffffff)
1408 return false; // overflow protection: don't accept number of options that doesn't fit signed int
1409 ++*buffer_max;
1410 return true;
1411 }
1412 };
1413
1414 /**
1415 * @internal
1416 * @brief An Action to pass to Parser::workhorse() that will store each parsed Option in
1417 * appropriate arrays (see Parser::parse()).
1418 */
1419 class Parser::StoreOptionAction: public Parser::Action
1420 {
1421 Parser& parser;
1422 Option* options;
1423 Option* buffer;
1424 int bufmax; //! Number of slots in @c buffer. @c -1 means "large enough".
1425 public:
1426 /**
1427 * @brief Creates a new StoreOption action.
1428 * @param parser_ the parser whose op_count should be updated.
1429 * @param options_ each Option @c o is chained into the linked list @c options_[o.desc->index]
1430 * @param buffer_ each Option is appended to this array as long as there's a free slot.
1431 * @param bufmax_ number of slots in @c buffer_. @c -1 means "large enough".
1432 */
StoreOptionAction(Parser & parser_,Option options_[],Option buffer_[],int bufmax_)1433 StoreOptionAction(Parser& parser_, Option options_[], Option buffer_[], int bufmax_) :
1434 parser(parser_), options(options_), buffer(buffer_), bufmax(bufmax_)
1435 {
1436 // find first empty slot in buffer (if any)
1437 int bufidx = 0;
1438 while ((bufmax < 0 || bufidx < bufmax) && buffer[bufidx])
1439 ++bufidx;
1440
1441 // set parser's optionCount
1442 parser.op_count = bufidx;
1443 }
1444
perform(Option & option)1445 bool perform(Option& option)
1446 {
1447 if (bufmax < 0 || parser.op_count < bufmax)
1448 {
1449 if (parser.op_count == 0x7fffffff)
1450 return false; // overflow protection: don't accept number of options that doesn't fit signed int
1451
1452 buffer[parser.op_count] = option;
1453 int idx = buffer[parser.op_count].desc->index;
1454 if (options[idx])
1455 options[idx].append(buffer[parser.op_count]);
1456 else
1457 options[idx] = buffer[parser.op_count];
1458 ++parser.op_count;
1459 }
1460 return true; // NOTE: an option that is discarded because of a full buffer is not fatal
1461 }
1462
finished(int numargs,const char ** args)1463 bool finished(int numargs, const char** args)
1464 {
1465 // only overwrite non-option argument list if there's at least 1
1466 // new non-option argument. Otherwise we keep the old list. This
1467 // makes it easy to use default non-option arguments.
1468 if (numargs > 0)
1469 {
1470 parser.nonop_count = numargs;
1471 parser.nonop_args = args;
1472 }
1473
1474 return true;
1475 }
1476 };
1477
parse(bool gnu,const Descriptor usage[],int argc,const char ** argv,Option options[],Option buffer[],int min_abbr_len,bool single_minus_longopt,int bufmax)1478 inline void Parser::parse(bool gnu, const Descriptor usage[], int argc, const char** argv, Option options[],
1479 Option buffer[], int min_abbr_len, bool single_minus_longopt, int bufmax)
1480 {
1481 StoreOptionAction action(*this, options, buffer, bufmax);
1482 err = !workhorse(gnu, usage, argc, argv, action, single_minus_longopt, true, min_abbr_len);
1483 }
1484
add(bool gnu,const Descriptor usage[],int argc,const char ** argv,int min_abbr_len,bool single_minus_longopt)1485 inline void Stats::add(bool gnu, const Descriptor usage[], int argc, const char** argv, int min_abbr_len,
1486 bool single_minus_longopt)
1487 {
1488 // determine size of options array. This is the greatest index used in the usage + 1
1489 int i = 0;
1490 while (usage[i].shortopt != 0)
1491 {
1492 if (usage[i].index + 1 >= options_max)
1493 options_max = (usage[i].index + 1) + 1; // 1 more than necessary as sentinel
1494
1495 ++i;
1496 }
1497
1498 CountOptionsAction action(&buffer_max);
1499 Parser::workhorse(gnu, usage, argc, argv, action, single_minus_longopt, false, min_abbr_len);
1500 }
1501
workhorse(bool gnu,const Descriptor usage[],int numargs,const char ** args,Action & action,bool single_minus_longopt,bool print_errors,int min_abbr_len)1502 inline bool Parser::workhorse(bool gnu, const Descriptor usage[], int numargs, const char** args, Action& action,
1503 bool single_minus_longopt, bool print_errors, int min_abbr_len)
1504 {
1505 // protect against NULL pointer
1506 if (args == 0)
1507 numargs = 0;
1508
1509 int nonops = 0;
1510
1511 while (numargs != 0 && *args != 0)
1512 {
1513 const char* param = *args; // param can be --long-option, -srto or non-option argument
1514
1515 // in POSIX mode the first non-option argument terminates the option list
1516 // a lone minus character is a non-option argument
1517 if (param[0] != '-' || param[1] == 0)
1518 {
1519 if (gnu)
1520 {
1521 ++nonops;
1522 ++args;
1523 if (numargs > 0)
1524 --numargs;
1525 continue;
1526 }
1527 else
1528 break;
1529 }
1530
1531 // -- terminates the option list. The -- itself is skipped.
1532 if (param[1] == '-' && param[2] == 0)
1533 {
1534 shift(args, nonops);
1535 ++args;
1536 if (numargs > 0)
1537 --numargs;
1538 break;
1539 }
1540
1541 bool handle_short_options;
1542 const char* longopt_name;
1543 if (param[1] == '-') // if --long-option
1544 {
1545 handle_short_options = false;
1546 longopt_name = param + 2;
1547 }
1548 else
1549 {
1550 handle_short_options = true;
1551 longopt_name = param + 1; //for testing a potential -long-option
1552 }
1553
1554 bool try_single_minus_longopt = single_minus_longopt;
1555 bool have_more_args = (numargs > 1 || numargs < 0); // is referencing argv[1] valid?
1556
1557 do // loop over short options in group, for long options the body is executed only once
1558 {
1559 int idx;
1560
1561 const char* optarg;
1562
1563 /******************** long option **********************/
1564 if (handle_short_options == false || try_single_minus_longopt)
1565 {
1566 idx = 0;
1567 while (usage[idx].longopt != 0 && !streq(usage[idx].longopt, longopt_name))
1568 ++idx;
1569
1570 if (usage[idx].longopt == 0 && min_abbr_len > 0) // if we should try to match abbreviated long options
1571 {
1572 int i1 = 0;
1573 while (usage[i1].longopt != 0 && !streqabbr(usage[i1].longopt, longopt_name, min_abbr_len))
1574 ++i1;
1575 if (usage[i1].longopt != 0)
1576 { // now test if the match is unambiguous by checking for another match
1577 int i2 = i1 + 1;
1578 while (usage[i2].longopt != 0 && !streqabbr(usage[i2].longopt, longopt_name, min_abbr_len))
1579 ++i2;
1580
1581 if (usage[i2].longopt == 0) // if there was no second match it's unambiguous, so accept i1 as idx
1582 idx = i1;
1583 }
1584 }
1585
1586 // if we found something, disable handle_short_options (only relevant if single_minus_longopt)
1587 if (usage[idx].longopt != 0)
1588 handle_short_options = false;
1589
1590 try_single_minus_longopt = false; // prevent looking for longopt in the middle of shortopt group
1591
1592 optarg = longopt_name;
1593 while (*optarg != 0 && *optarg != '=')
1594 ++optarg;
1595 if (*optarg == '=') // attached argument
1596 ++optarg;
1597 else
1598 // possibly detached argument
1599 optarg = (have_more_args ? args[1] : 0);
1600 }
1601
1602 /************************ short option ***********************************/
1603 if (handle_short_options)
1604 {
1605 if (*++param == 0) // point at the 1st/next option character
1606 break; // end of short option group
1607
1608 idx = 0;
1609 while (usage[idx].shortopt != 0 && !instr(*param, usage[idx].shortopt))
1610 ++idx;
1611
1612 if (param[1] == 0) // if the potential argument is separate
1613 optarg = (have_more_args ? args[1] : 0);
1614 else
1615 // if the potential argument is attached
1616 optarg = param + 1;
1617 }
1618
1619 const Descriptor* descriptor = &usage[idx];
1620
1621 if (descriptor->shortopt == 0) /************** unknown option ********************/
1622 {
1623 // look for dummy entry (shortopt == "" and longopt == "") to use as Descriptor for unknown options
1624 idx = 0;
1625 while (usage[idx].shortopt != 0 && (usage[idx].shortopt[0] != 0 || usage[idx].longopt[0] != 0))
1626 ++idx;
1627 descriptor = (usage[idx].shortopt == 0 ? 0 : &usage[idx]);
1628 }
1629
1630 if (descriptor != 0)
1631 {
1632 Option option(descriptor, param, optarg);
1633 switch (descriptor->check_arg(option, print_errors))
1634 {
1635 case ARG_ILLEGAL:
1636 return false; // fatal
1637 case ARG_OK:
1638 // skip one element of the argument vector, if it's a separated argument
1639 if (optarg != 0 && have_more_args && optarg == args[1])
1640 {
1641 shift(args, nonops);
1642 if (numargs > 0)
1643 --numargs;
1644 ++args;
1645 }
1646
1647 // No further short options are possible after an argument
1648 handle_short_options = false;
1649
1650 break;
1651 case ARG_IGNORE:
1652 case ARG_NONE:
1653 option.arg = 0;
1654 break;
1655 }
1656
1657 if (!action.perform(option))
1658 return false;
1659 }
1660
1661 } while (handle_short_options);
1662
1663 shift(args, nonops);
1664 ++args;
1665 if (numargs > 0)
1666 --numargs;
1667
1668 } // while
1669
1670 if (numargs > 0 && *args == 0) // It's a bug in the caller if numargs is greater than the actual number
1671 numargs = 0; // of arguments, but as a service to the user we fix this if we spot it.
1672
1673 if (numargs < 0) // if we don't know the number of remaining non-option arguments
1674 { // we need to count them
1675 numargs = 0;
1676 while (args[numargs] != 0)
1677 ++numargs;
1678 }
1679
1680 return action.finished(numargs + nonops, args - nonops);
1681 }
1682
1683 /**
1684 * @internal
1685 * @brief The implementation of option::printUsage().
1686 */
1687 struct PrintUsageImplementation
1688 {
1689 /**
1690 * @internal
1691 * @brief Interface for Functors that write (part of) a string somewhere.
1692 */
1693 struct IStringWriter
1694 {
1695 /**
1696 * @brief Writes the given number of chars beginning at the given pointer somewhere.
1697 */
operatorPrintUsageImplementation::IStringWriter1698 virtual void operator()(const char*, int)
1699 {
1700 }
1701 };
1702
1703 /**
1704 * @internal
1705 * @brief Encapsulates a function with signature <code>func(string, size)</code> where
1706 * string can be initialized with a const char* and size with an int.
1707 */
1708 template<typename Function>
1709 struct FunctionWriter: public IStringWriter
1710 {
1711 Function* write;
1712
operatorPrintUsageImplementation::FunctionWriter1713 virtual void operator()(const char* str, int size)
1714 {
1715 (*write)(str, size);
1716 }
1717
FunctionWriterPrintUsageImplementation::FunctionWriter1718 FunctionWriter(Function* w) :
1719 write(w)
1720 {
1721 }
1722 };
1723
1724 /**
1725 * @internal
1726 * @brief Encapsulates a reference to an object with a <code>write(string, size)</code>
1727 * method like that of @c std::ostream.
1728 */
1729 template<typename OStream>
1730 struct OStreamWriter: public IStringWriter
1731 {
1732 OStream& ostream;
1733
operatorPrintUsageImplementation::OStreamWriter1734 virtual void operator()(const char* str, int size)
1735 {
1736 ostream.write(str, size);
1737 }
1738
OStreamWriterPrintUsageImplementation::OStreamWriter1739 OStreamWriter(OStream& o) :
1740 ostream(o)
1741 {
1742 }
1743 };
1744
1745 /**
1746 * @internal
1747 * @brief Like OStreamWriter but encapsulates a @c const reference, which is
1748 * typically a temporary object of a user class.
1749 */
1750 template<typename Temporary>
1751 struct TemporaryWriter: public IStringWriter
1752 {
1753 const Temporary& userstream;
1754
operatorPrintUsageImplementation::TemporaryWriter1755 virtual void operator()(const char* str, int size)
1756 {
1757 userstream.write(str, size);
1758 }
1759
TemporaryWriterPrintUsageImplementation::TemporaryWriter1760 TemporaryWriter(const Temporary& u) :
1761 userstream(u)
1762 {
1763 }
1764 };
1765
1766 /**
1767 * @internal
1768 * @brief Encapsulates a function with the signature <code>func(fd, string, size)</code> (the
1769 * signature of the @c write() system call)
1770 * where fd can be initialized from an int, string from a const char* and size from an int.
1771 */
1772 template<typename Syscall>
1773 struct SyscallWriter: public IStringWriter
1774 {
1775 Syscall* write;
1776 int fd;
1777
operatorPrintUsageImplementation::SyscallWriter1778 virtual void operator()(const char* str, int size)
1779 {
1780 (*write)(fd, str, size);
1781 }
1782
SyscallWriterPrintUsageImplementation::SyscallWriter1783 SyscallWriter(Syscall* w, int f) :
1784 write(w), fd(f)
1785 {
1786 }
1787 };
1788
1789 /**
1790 * @internal
1791 * @brief Encapsulates a function with the same signature as @c std::fwrite().
1792 */
1793 template<typename Function, typename Stream>
1794 struct StreamWriter: public IStringWriter
1795 {
1796 Function* fwrite;
1797 Stream* stream;
1798
operatorPrintUsageImplementation::StreamWriter1799 virtual void operator()(const char* str, int size)
1800 {
1801 (*fwrite)(str, size, 1, stream);
1802 }
1803
StreamWriterPrintUsageImplementation::StreamWriter1804 StreamWriter(Function* w, Stream* s) :
1805 fwrite(w), stream(s)
1806 {
1807 }
1808 };
1809
1810 /**
1811 * @internal
1812 * @brief Sets <code> i1 = max(i1, i2) </code>
1813 */
upmaxPrintUsageImplementation1814 static void upmax(int& i1, int i2)
1815 {
1816 i1 = (i1 >= i2 ? i1 : i2);
1817 }
1818
1819 /**
1820 * @internal
1821 * @brief Moves the "cursor" to column @c want_x assuming it is currently at column @c x
1822 * and sets @c x=want_x .
1823 * If <code> x > want_x </code>, a line break is output before indenting.
1824 *
1825 * @param write Spaces and possibly a line break are written via this functor to get
1826 * the desired indentation @c want_x .
1827 * @param[in,out] x the current indentation. Set to @c want_x by this method.
1828 * @param want_x the desired indentation.
1829 */
indentPrintUsageImplementation1830 static void indent(IStringWriter& write, int& x, int want_x)
1831 {
1832 int indent = want_x - x;
1833 if (indent < 0)
1834 {
1835 write("\n", 1);
1836 indent = want_x;
1837 }
1838
1839 if (indent > 0)
1840 {
1841 char space = ' ';
1842 for (int i = 0; i < indent; ++i)
1843 write(&space, 1);
1844 x = want_x;
1845 }
1846 }
1847
1848 /**
1849 * @brief Returns true if ch is the unicode code point of a wide character.
1850 *
1851 * @note
1852 * The following character ranges are treated as wide
1853 * @code
1854 * 1100..115F
1855 * 2329..232A (just 2 characters!)
1856 * 2E80..A4C6 except for 303F
1857 * A960..A97C
1858 * AC00..D7FB
1859 * F900..FAFF
1860 * FE10..FE6B
1861 * FF01..FF60
1862 * FFE0..FFE6
1863 * 1B000......
1864 * @endcode
1865 */
isWideCharPrintUsageImplementation1866 static bool isWideChar(unsigned ch)
1867 {
1868 if (ch == 0x303F)
1869 return false;
1870
1871 return ((0x1100 <= ch && ch <= 0x115F) || (0x2329 <= ch && ch <= 0x232A) || (0x2E80 <= ch && ch <= 0xA4C6)
1872 || (0xA960 <= ch && ch <= 0xA97C) || (0xAC00 <= ch && ch <= 0xD7FB) || (0xF900 <= ch && ch <= 0xFAFF)
1873 || (0xFE10 <= ch && ch <= 0xFE6B) || (0xFF01 <= ch && ch <= 0xFF60) || (0xFFE0 <= ch && ch <= 0xFFE6)
1874 || (0x1B000 <= ch));
1875 }
1876
1877 /**
1878 * @internal
1879 * @brief Splits a @c Descriptor[] array into tables, rows, lines and columns and
1880 * iterates over these components.
1881 *
1882 * The top-level organizational unit is the @e table.
1883 * A table begins at a Descriptor with @c help!=NULL and extends up to
1884 * a Descriptor with @c help==NULL.
1885 *
1886 * A table consists of @e rows. Due to line-wrapping and explicit breaks
1887 * a row may take multiple lines on screen. Rows within the table are separated
1888 * by \\n. They never cross Descriptor boundaries. This means a row ends either
1889 * at \\n or the 0 at the end of the help string.
1890 *
1891 * A row consists of columns/cells. Columns/cells within a row are separated by \\t.
1892 * Line breaks within a cell are marked by \\v.
1893 *
1894 * Rows in the same table need not have the same number of columns/cells. The
1895 * extreme case are interjections, which are rows that contain neither \\t nor \\v.
1896 * These are NOT treated specially by LinePartIterator, but they are treated
1897 * specially by printUsage().
1898 *
1899 * LinePartIterator iterates through the usage at 3 levels: table, row and part.
1900 * Tables and rows are as described above. A @e part is a line within a cell.
1901 * LinePartIterator iterates through 1st parts of all cells, then through the 2nd
1902 * parts of all cells (if any),... @n
1903 * Example: The row <code> "1 \v 3 \t 2 \v 4" </code> has 2 cells/columns and 4 parts.
1904 * The parts will be returned in the order 1, 2, 3, 4.
1905 *
1906 * It is possible that some cells have fewer parts than others. In this case
1907 * LinePartIterator will "fill up" these cells with 0-length parts. IOW, LinePartIterator
1908 * always returns the same number of parts for each column. Note that this is different
1909 * from the way rows and columns are handled. LinePartIterator does @e not guarantee that
1910 * the same number of columns will be returned for each row.
1911 *
1912 */
1913 class LinePartIterator
1914 {
1915 const Descriptor* tablestart; //!< The 1st descriptor of the current table.
1916 const Descriptor* rowdesc; //!< The Descriptor that contains the current row.
1917 const char* rowstart; //!< Ptr to 1st character of current row within rowdesc->help.
1918 const char* ptr; //!< Ptr to current part within the current row.
1919 int col; //!< Index of current column.
1920 int len; //!< Length of the current part (that ptr points at) in BYTES
1921 int screenlen; //!< Length of the current part in screen columns (taking narrow/wide chars into account).
1922 int max_line_in_block; //!< Greatest index of a line within the block. This is the number of \\v within the cell with the most \\vs.
1923 int line_in_block; //!< Line index within the current cell of the current part.
1924 int target_line_in_block; //!< Line index of the parts we should return to the user on this iteration.
1925 bool hit_target_line; //!< Flag whether we encountered a part with line index target_line_in_block in the current cell.
1926
1927 /**
1928 * @brief Determines the byte and character lengths of the part at @ref ptr and
1929 * stores them in @ref len and @ref screenlen respectively.
1930 */
update_lengthPrintUsageImplementation1931 void update_length()
1932 {
1933 screenlen = 0;
1934 for (len = 0; ptr[len] != 0 && ptr[len] != '\v' && ptr[len] != '\t' && ptr[len] != '\n'; ++len)
1935 {
1936 ++screenlen;
1937 unsigned ch = (unsigned char) ptr[len];
1938 if (ch > 0xC1) // everything <= 0xC1 (yes, even 0xC1 itself) is not a valid UTF-8 start byte
1939 {
1940 // int __builtin_clz (unsigned int x)
1941 // Returns the number of leading 0-bits in x, starting at the most significant bit
1942 unsigned mask = (unsigned) -1 >> __builtin_clz(ch ^ 0xff);
1943 ch = ch & mask; // mask out length bits, we don't verify their correctness
1944 while (((unsigned char) ptr[len + 1] ^ 0x80) <= 0x3F) // while next byte is continuation byte
1945 {
1946 ch = (ch << 6) ^ (unsigned char) ptr[len + 1] ^ 0x80; // add continuation to char code
1947 ++len;
1948 }
1949 // ch is the decoded unicode code point
1950 if (ch >= 0x1100 && isWideChar(ch)) // the test for 0x1100 is here to avoid the function call in the Latin case
1951 ++screenlen;
1952 }
1953 }
1954 }
1955
1956 public:
1957 //! @brief Creates an iterator for @c usage.
LinePartIteratorPrintUsageImplementation1958 LinePartIterator(const Descriptor usage[]) :
1959 tablestart(usage), rowdesc(0), rowstart(0), ptr(0), col(-1), len(0), max_line_in_block(0), line_in_block(0),
1960 target_line_in_block(0), hit_target_line(true)
1961 {
1962 }
1963
1964 /**
1965 * @brief Moves iteration to the next table (if any). Has to be called once on a new
1966 * LinePartIterator to move to the 1st table.
1967 * @retval false if moving to next table failed because no further table exists.
1968 */
nextTablePrintUsageImplementation1969 bool nextTable()
1970 {
1971 // If this is NOT the first time nextTable() is called after the constructor,
1972 // then skip to the next table break (i.e. a Descriptor with help == 0)
1973 if (rowdesc != 0)
1974 {
1975 while (tablestart->help != 0 && tablestart->shortopt != 0)
1976 ++tablestart;
1977 }
1978
1979 // Find the next table after the break (if any)
1980 while (tablestart->help == 0 && tablestart->shortopt != 0)
1981 ++tablestart;
1982
1983 restartTable();
1984 return rowstart != 0;
1985 }
1986
1987 /**
1988 * @brief Reset iteration to the beginning of the current table.
1989 */
restartTablePrintUsageImplementation1990 void restartTable()
1991 {
1992 rowdesc = tablestart;
1993 rowstart = tablestart->help;
1994 ptr = 0;
1995 }
1996
1997 /**
1998 * @brief Moves iteration to the next row (if any). Has to be called once after each call to
1999 * @ref nextTable() to move to the 1st row of the table.
2000 * @retval false if moving to next row failed because no further row exists.
2001 */
nextRowPrintUsageImplementation2002 bool nextRow()
2003 {
2004 if (ptr == 0)
2005 {
2006 restartRow();
2007 return rowstart != 0;
2008 }
2009
2010 while (*ptr != 0 && *ptr != '\n')
2011 ++ptr;
2012
2013 if (*ptr == 0)
2014 {
2015 if ((rowdesc + 1)->help == 0) // table break
2016 return false;
2017
2018 ++rowdesc;
2019 rowstart = rowdesc->help;
2020 }
2021 else // if (*ptr == '\n')
2022 {
2023 rowstart = ptr + 1;
2024 }
2025
2026 restartRow();
2027 return true;
2028 }
2029
2030 /**
2031 * @brief Reset iteration to the beginning of the current row.
2032 */
restartRowPrintUsageImplementation2033 void restartRow()
2034 {
2035 ptr = rowstart;
2036 col = -1;
2037 len = 0;
2038 screenlen = 0;
2039 max_line_in_block = 0;
2040 line_in_block = 0;
2041 target_line_in_block = 0;
2042 hit_target_line = true;
2043 }
2044
2045 /**
2046 * @brief Moves iteration to the next part (if any). Has to be called once after each call to
2047 * @ref nextRow() to move to the 1st part of the row.
2048 * @retval false if moving to next part failed because no further part exists.
2049 *
2050 * See @ref LinePartIterator for details about the iteration.
2051 */
nextPrintUsageImplementation2052 bool next()
2053 {
2054 if (ptr == 0)
2055 return false;
2056
2057 if (col == -1)
2058 {
2059 col = 0;
2060 update_length();
2061 return true;
2062 }
2063
2064 ptr += len;
2065 while (true)
2066 {
2067 switch (*ptr)
2068 {
2069 case '\v':
2070 upmax(max_line_in_block, ++line_in_block);
2071 ++ptr;
2072 break;
2073 case '\t':
2074 if (!hit_target_line) // if previous column did not have the targetline
2075 { // then "insert" a 0-length part
2076 update_length();
2077 hit_target_line = true;
2078 return true;
2079 }
2080
2081 hit_target_line = false;
2082 line_in_block = 0;
2083 ++col;
2084 ++ptr;
2085 break;
2086 case 0:
2087 case '\n':
2088 if (!hit_target_line) // if previous column did not have the targetline
2089 { // then "insert" a 0-length part
2090 update_length();
2091 hit_target_line = true;
2092 return true;
2093 }
2094
2095 if (++target_line_in_block > max_line_in_block)
2096 {
2097 update_length();
2098 return false;
2099 }
2100
2101 hit_target_line = false;
2102 line_in_block = 0;
2103 col = 0;
2104 ptr = rowstart;
2105 continue;
2106 default:
2107 ++ptr;
2108 continue;
2109 } // switch
2110
2111 if (line_in_block == target_line_in_block)
2112 {
2113 update_length();
2114 hit_target_line = true;
2115 return true;
2116 }
2117 } // while
2118 }
2119
2120 /**
2121 * @brief Returns the index (counting from 0) of the column in which
2122 * the part pointed to by @ref data() is located.
2123 */
columnPrintUsageImplementation2124 int column()
2125 {
2126 return col;
2127 }
2128
2129 /**
2130 * @brief Returns the index (counting from 0) of the line within the current column
2131 * this part belongs to.
2132 */
linePrintUsageImplementation2133 int line()
2134 {
2135 return target_line_in_block; // NOT line_in_block !!! It would be wrong if !hit_target_line
2136 }
2137
2138 /**
2139 * @brief Returns the length of the part pointed to by @ref data() in raw chars (not UTF-8 characters).
2140 */
lengthPrintUsageImplementation2141 int length()
2142 {
2143 return len;
2144 }
2145
2146 /**
2147 * @brief Returns the width in screen columns of the part pointed to by @ref data().
2148 * Takes multi-byte UTF-8 sequences and wide characters into account.
2149 */
screenLengthPrintUsageImplementation2150 int screenLength()
2151 {
2152 return screenlen;
2153 }
2154
2155 /**
2156 * @brief Returns the current part of the iteration.
2157 */
dataPrintUsageImplementation2158 const char* data()
2159 {
2160 return ptr;
2161 }
2162 };
2163
2164 /**
2165 * @internal
2166 * @brief Takes input and line wraps it, writing out one line at a time so that
2167 * it can be interleaved with output from other columns.
2168 *
2169 * The LineWrapper is used to handle the last column of each table as well as interjections.
2170 * The LineWrapper is called once for each line of output. If the data given to it fits
2171 * into the designated width of the last column it is simply written out. If there
2172 * is too much data, an appropriate split point is located and only the data up to this
2173 * split point is written out. The rest of the data is queued for the next line.
2174 * That way the last column can be line wrapped and interleaved with data from
2175 * other columns. The following example makes this clearer:
2176 * @code
2177 * Column 1,1 Column 2,1 This is a long text
2178 * Column 1,2 Column 2,2 that does not fit into
2179 * a single line.
2180 * @endcode
2181 *
2182 * The difficulty in producing this output is that the whole string
2183 * "This is a long text that does not fit into a single line" is the
2184 * 1st and only part of column 3. In order to produce the above
2185 * output the string must be output piecemeal, interleaved with
2186 * the data from the other columns.
2187 */
2188 class LineWrapper
2189 {
2190 static const int bufmask = 15; //!< Must be a power of 2 minus 1.
2191 /**
2192 * @brief Ring buffer for length component of pair (data, length).
2193 */
2194 int lenbuf[bufmask + 1];
2195 /**
2196 * @brief Ring buffer for data component of pair (data, length).
2197 */
2198 const char* datbuf[bufmask + 1];
2199 /**
2200 * @brief The indentation of the column to which the LineBuffer outputs. LineBuffer
2201 * assumes that the indentation has already been written when @ref process()
2202 * is called, so this value is only used when a buffer flush requires writing
2203 * additional lines of output.
2204 */
2205 int x;
2206 /**
2207 * @brief The width of the column to line wrap.
2208 */
2209 int width;
2210 int head; //!< @brief index for next write
2211 int tail; //!< @brief index for next read - 1 (i.e. increment tail BEFORE read)
2212
2213 /**
2214 * @brief Multiple methods of LineWrapper may decide to flush part of the buffer to
2215 * free up space. The contract of process() says that only 1 line is output. So
2216 * this variable is used to track whether something has output a line. It is
2217 * reset at the beginning of process() and checked at the end to decide if
2218 * output has already occurred or is still needed.
2219 */
2220 bool wrote_something;
2221
buf_emptyPrintUsageImplementation2222 bool buf_empty()
2223 {
2224 return ((tail + 1) & bufmask) == head;
2225 }
2226
buf_fullPrintUsageImplementation2227 bool buf_full()
2228 {
2229 return tail == head;
2230 }
2231
buf_storePrintUsageImplementation2232 void buf_store(const char* data, int len)
2233 {
2234 lenbuf[head] = len;
2235 datbuf[head] = data;
2236 head = (head + 1) & bufmask;
2237 }
2238
2239 //! @brief Call BEFORE reading ...buf[tail].
buf_nextPrintUsageImplementation2240 void buf_next()
2241 {
2242 tail = (tail + 1) & bufmask;
2243 }
2244
2245 /**
2246 * @brief Writes (data,len) into the ring buffer. If the buffer is full, a single line
2247 * is flushed out of the buffer into @c write.
2248 */
outputPrintUsageImplementation2249 void output(IStringWriter& write, const char* data, int len)
2250 {
2251 if (buf_full())
2252 write_one_line(write);
2253
2254 buf_store(data, len);
2255 }
2256
2257 /**
2258 * @brief Writes a single line of output from the buffer to @c write.
2259 */
write_one_linePrintUsageImplementation2260 void write_one_line(IStringWriter& write)
2261 {
2262 if (wrote_something) // if we already wrote something, we need to start a new line
2263 {
2264 write("\n", 1);
2265 int _ = 0;
2266 indent(write, _, x);
2267 }
2268
2269 if (!buf_empty())
2270 {
2271 buf_next();
2272 write(datbuf[tail], lenbuf[tail]);
2273 }
2274
2275 wrote_something = true;
2276 }
2277 public:
2278
2279 /**
2280 * @brief Writes out all remaining data from the LineWrapper using @c write.
2281 * Unlike @ref process() this method indents all lines including the first and
2282 * will output a \\n at the end (but only if something has been written).
2283 */
flushPrintUsageImplementation2284 void flush(IStringWriter& write)
2285 {
2286 if (buf_empty())
2287 return;
2288 int _ = 0;
2289 indent(write, _, x);
2290 wrote_something = false;
2291 while (!buf_empty())
2292 write_one_line(write);
2293 write("\n", 1);
2294 }
2295
2296 /**
2297 * @brief Process, wrap and output the next piece of data.
2298 *
2299 * process() will output at least one line of output. This is not necessarily
2300 * the @c data passed in. It may be data queued from a prior call to process().
2301 * If the internal buffer is full, more than 1 line will be output.
2302 *
2303 * process() assumes that the a proper amount of indentation has already been
2304 * output. It won't write any further indentation before the 1st line. If
2305 * more than 1 line is written due to buffer constraints, the lines following
2306 * the first will be indented by this method, though.
2307 *
2308 * No \\n is written by this method after the last line that is written.
2309 *
2310 * @param write where to write the data.
2311 * @param data the new chunk of data to write.
2312 * @param len the length of the chunk of data to write.
2313 */
processPrintUsageImplementation2314 void process(IStringWriter& write, const char* data, int len)
2315 {
2316 wrote_something = false;
2317
2318 while (len > 0)
2319 {
2320 if (len <= width) // quick test that works because utf8width <= len (all wide chars have at least 2 bytes)
2321 {
2322 output(write, data, len);
2323 len = 0;
2324 }
2325 else // if (len > width) it's possible (but not guaranteed) that utf8len > width
2326 {
2327 int utf8width = 0;
2328 int maxi = 0;
2329 while (maxi < len && utf8width < width)
2330 {
2331 int charbytes = 1;
2332 unsigned ch = (unsigned char) data[maxi];
2333 if (ch > 0xC1) // everything <= 0xC1 (yes, even 0xC1 itself) is not a valid UTF-8 start byte
2334 {
2335 // int __builtin_clz (unsigned int x)
2336 // Returns the number of leading 0-bits in x, starting at the most significant bit
2337 unsigned mask = (unsigned) -1 >> __builtin_clz(ch ^ 0xff);
2338 ch = ch & mask; // mask out length bits, we don't verify their correctness
2339 while ((maxi + charbytes < len) && //
2340 (((unsigned char) data[maxi + charbytes] ^ 0x80) <= 0x3F)) // while next byte is continuation byte
2341 {
2342 ch = (ch << 6) ^ (unsigned char) data[maxi + charbytes] ^ 0x80; // add continuation to char code
2343 ++charbytes;
2344 }
2345 // ch is the decoded unicode code point
2346 if (ch >= 0x1100 && isWideChar(ch)) // the test for 0x1100 is here to avoid the function call in the Latin case
2347 {
2348 if (utf8width + 2 > width)
2349 break;
2350 ++utf8width;
2351 }
2352 }
2353 ++utf8width;
2354 maxi += charbytes;
2355 }
2356
2357 // data[maxi-1] is the last byte of the UTF-8 sequence of the last character that fits
2358 // onto the 1st line. If maxi == len, all characters fit on the line.
2359
2360 if (maxi == len)
2361 {
2362 output(write, data, len);
2363 len = 0;
2364 }
2365 else // if (maxi < len) at least 1 character (data[maxi] that is) doesn't fit on the line
2366 {
2367 int i;
2368 for (i = maxi; i >= 0; --i)
2369 if (data[i] == ' ')
2370 break;
2371
2372 if (i >= 0)
2373 {
2374 output(write, data, i);
2375 data += i + 1;
2376 len -= i + 1;
2377 }
2378 else // did not find a space to split at => split before data[maxi]
2379 { // data[maxi] is always the beginning of a character, never a continuation byte
2380 output(write, data, maxi);
2381 data += maxi;
2382 len -= maxi;
2383 }
2384 }
2385 }
2386 }
2387 if (!wrote_something) // if we didn't already write something to make space in the buffer
2388 write_one_line(write); // write at most one line of actual output
2389 }
2390
2391 /**
2392 * @brief Constructs a LineWrapper that wraps its output to fit into
2393 * screen columns @c x1 (incl.) to @c x2 (excl.).
2394 *
2395 * @c x1 gives the indentation LineWrapper uses if it needs to indent.
2396 */
LineWrapperPrintUsageImplementation2397 LineWrapper(int x1, int x2) :
2398 x(x1), width(x2 - x1), head(0), tail(bufmask)
2399 {
2400 if (width < 2) // because of wide characters we need at least width 2 or the code breaks
2401 width = 2;
2402 }
2403 };
2404
2405 /**
2406 * @internal
2407 * @brief This is the implementation that is shared between all printUsage() templates.
2408 * Because all printUsage() templates share this implementation, there is no template bloat.
2409 */
2410 static void printUsage(IStringWriter& write, const Descriptor usage[], int width = 80, //
2411 int last_column_min_percent = 50, int last_column_own_line_max_percent = 75)
2412 {
2413 if (width < 1) // protect against nonsense values
2414 width = 80;
2415
2416 if (width > 10000) // protect against overflow in the following computation
2417 width = 10000;
2418
2419 int last_column_min_width = ((width * last_column_min_percent) + 50) / 100;
2420 int last_column_own_line_max_width = ((width * last_column_own_line_max_percent) + 50) / 100;
2421 if (last_column_own_line_max_width == 0)
2422 last_column_own_line_max_width = 1;
2423
2424 LinePartIterator part(usage);
2425 while (part.nextTable())
2426 {
2427
2428 /***************** Determine column widths *******************************/
2429
2430 const int maxcolumns = 8; // 8 columns are enough for everyone
2431 int col_width[maxcolumns];
2432 int lastcolumn;
2433 int leftwidth;
2434 int overlong_column_threshold = 10000;
2435 do
2436 {
2437 lastcolumn = 0;
2438 for (int i = 0; i < maxcolumns; ++i)
2439 col_width[i] = 0;
2440
2441 part.restartTable();
2442 while (part.nextRow())
2443 {
2444 while (part.next())
2445 {
2446 if (part.column() < maxcolumns)
2447 {
2448 upmax(lastcolumn, part.column());
2449 if (part.screenLength() < overlong_column_threshold)
2450 // We don't let rows that don't use table separators (\t or \v) influence
2451 // the width of column 0. This allows the user to interject section headers
2452 // or explanatory paragraphs that do not participate in the table layout.
2453 if (part.column() > 0 || part.line() > 0 || part.data()[part.length()] == '\t'
2454 || part.data()[part.length()] == '\v')
2455 upmax(col_width[part.column()], part.screenLength());
2456 }
2457 }
2458 }
2459
2460 /*
2461 * If the last column doesn't fit on the same
2462 * line as the other columns, we can fix that by starting it on its own line.
2463 * However we can't do this for any of the columns 0..lastcolumn-1.
2464 * If their sum exceeds the maximum width we try to fix this by iteratively
2465 * ignoring the widest line parts in the width determination until
2466 * we arrive at a series of column widths that fit into one line.
2467 * The result is a layout where everything is nicely formatted
2468 * except for a few overlong fragments.
2469 * */
2470
2471 leftwidth = 0;
2472 overlong_column_threshold = 0;
2473 for (int i = 0; i < lastcolumn; ++i)
2474 {
2475 leftwidth += col_width[i];
2476 upmax(overlong_column_threshold, col_width[i]);
2477 }
2478
2479 } while (leftwidth > width);
2480
2481 /**************** Determine tab stops and last column handling **********************/
2482
2483 int tabstop[maxcolumns];
2484 tabstop[0] = 0;
2485 for (int i = 1; i < maxcolumns; ++i)
2486 tabstop[i] = tabstop[i - 1] + col_width[i - 1];
2487
2488 int rightwidth = width - tabstop[lastcolumn];
2489 bool print_last_column_on_own_line = false;
2490 if (rightwidth < last_column_min_width && // if we don't have the minimum requested width for the last column
2491 ( col_width[lastcolumn] == 0 || // and all last columns are > overlong_column_threshold
2492 rightwidth < col_width[lastcolumn] // or there is at least one last column that requires more than the space available
2493 )
2494 )
2495 {
2496 print_last_column_on_own_line = true;
2497 rightwidth = last_column_own_line_max_width;
2498 }
2499
2500 // If lastcolumn == 0 we must disable print_last_column_on_own_line because
2501 // otherwise 2 copies of the last (and only) column would be output.
2502 // Actually this is just defensive programming. It is currently not
2503 // possible that lastcolumn==0 and print_last_column_on_own_line==true
2504 // at the same time, because lastcolumn==0 => tabstop[lastcolumn] == 0 =>
2505 // rightwidth==width => rightwidth>=last_column_min_width (unless someone passes
2506 // a bullshit value >100 for last_column_min_percent) => the above if condition
2507 // is false => print_last_column_on_own_line==false
2508 if (lastcolumn == 0)
2509 print_last_column_on_own_line = false;
2510
2511 LineWrapper lastColumnLineWrapper(width - rightwidth, width);
2512 LineWrapper interjectionLineWrapper(0, width);
2513
2514 part.restartTable();
2515
2516 /***************** Print out all rows of the table *************************************/
2517
2518 while (part.nextRow())
2519 {
2520 int x = -1;
2521 while (part.next())
2522 {
2523 if (part.column() > lastcolumn)
2524 continue; // drop excess columns (can happen if lastcolumn == maxcolumns-1)
2525
2526 if (part.column() == 0)
2527 {
2528 if (x >= 0)
2529 write("\n", 1);
2530 x = 0;
2531 }
2532
2533 indent(write, x, tabstop[part.column()]);
2534
2535 if ((part.column() < lastcolumn)
2536 && (part.column() > 0 || part.line() > 0 || part.data()[part.length()] == '\t'
2537 || part.data()[part.length()] == '\v'))
2538 {
2539 write(part.data(), part.length());
2540 x += part.screenLength();
2541 }
2542 else // either part.column() == lastcolumn or we are in the special case of
2543 // an interjection that doesn't contain \v or \t
2544 {
2545 // NOTE: This code block is not necessarily executed for
2546 // each line, because some rows may have fewer columns.
2547
2548 LineWrapper& lineWrapper = (part.column() == 0) ? interjectionLineWrapper : lastColumnLineWrapper;
2549
2550 if (!print_last_column_on_own_line || part.column() != lastcolumn)
2551 lineWrapper.process(write, part.data(), part.length());
2552 }
2553 } // while
2554
2555 if (print_last_column_on_own_line)
2556 {
2557 part.restartRow();
2558 while (part.next())
2559 {
2560 if (part.column() == lastcolumn)
2561 {
2562 write("\n", 1);
2563 int _ = 0;
2564 indent(write, _, width - rightwidth);
2565 lastColumnLineWrapper.process(write, part.data(), part.length());
2566 }
2567 }
2568 }
2569
2570 write("\n", 1);
2571 lastColumnLineWrapper.flush(write);
2572 interjectionLineWrapper.flush(write);
2573 }
2574 }
2575 }
2576
2577 }
2578 ;
2579
2580 /**
2581 * @brief Outputs a nicely formatted usage string with support for multi-column formatting
2582 * and line-wrapping.
2583 *
2584 * printUsage() takes the @c help texts of a Descriptor[] array and formats them into
2585 * a usage message, wrapping lines to achieve the desired output width.
2586 *
2587 * <b>Table formatting:</b>
2588 *
2589 * Aside from plain strings which are simply line-wrapped, the usage may contain tables. Tables
2590 * are used to align elements in the output.
2591 *
2592 * @code
2593 * // Without a table. The explanatory texts are not aligned.
2594 * -c, --create |Creates something.
2595 * -k, --kill |Destroys something.
2596 *
2597 * // With table formatting. The explanatory texts are aligned.
2598 * -c, --create |Creates something.
2599 * -k, --kill |Destroys something.
2600 * @endcode
2601 *
2602 * Table formatting removes the need to pad help texts manually with spaces to achieve
2603 * alignment. To create a table, simply insert \\t (tab) characters to separate the cells
2604 * within a row.
2605 *
2606 * @code
2607 * const option::Descriptor usage[] = {
2608 * {..., "-c, --create \tCreates something." },
2609 * {..., "-k, --kill \tDestroys something." }, ...
2610 * @endcode
2611 *
2612 * Note that you must include the minimum amount of space desired between cells yourself.
2613 * Table formatting will insert further spaces as needed to achieve alignment.
2614 *
2615 * You can insert line breaks within cells by using \\v (vertical tab).
2616 *
2617 * @code
2618 * const option::Descriptor usage[] = {
2619 * {..., "-c,\v--create \tCreates\vsomething." },
2620 * {..., "-k,\v--kill \tDestroys\vsomething." }, ...
2621 *
2622 * // results in
2623 *
2624 * -c, Creates
2625 * --create something.
2626 * -k, Destroys
2627 * --kill something.
2628 * @endcode
2629 *
2630 * You can mix lines that do not use \\t or \\v with those that do. The plain
2631 * lines will not mess up the table layout. Alignment of the table columns will
2632 * be maintained even across these interjections.
2633 *
2634 * @code
2635 * const option::Descriptor usage[] = {
2636 * {..., "-c, --create \tCreates something." },
2637 * {..., "----------------------------------" },
2638 * {..., "-k, --kill \tDestroys something." }, ...
2639 *
2640 * // results in
2641 *
2642 * -c, --create Creates something.
2643 * ----------------------------------
2644 * -k, --kill Destroys something.
2645 * @endcode
2646 *
2647 * You can have multiple tables within the same usage whose columns are
2648 * aligned independently. Simply insert a dummy Descriptor with @c help==0.
2649 *
2650 * @code
2651 * const option::Descriptor usage[] = {
2652 * {..., "Long options:" },
2653 * {..., "--very-long-option \tDoes something long." },
2654 * {..., "--ultra-super-mega-long-option \tTakes forever to complete." },
2655 * {..., 0 }, // ---------- table break -----------
2656 * {..., "Short options:" },
2657 * {..., "-s \tShort." },
2658 * {..., "-q \tQuick." }, ...
2659 *
2660 * // results in
2661 *
2662 * Long options:
2663 * --very-long-option Does something long.
2664 * --ultra-super-mega-long-option Takes forever to complete.
2665 * Short options:
2666 * -s Short.
2667 * -q Quick.
2668 *
2669 * // Without the table break it would be
2670 *
2671 * Long options:
2672 * --very-long-option Does something long.
2673 * --ultra-super-mega-long-option Takes forever to complete.
2674 * Short options:
2675 * -s Short.
2676 * -q Quick.
2677 * @endcode
2678 *
2679 * <b>Output methods:</b>
2680 *
2681 * Because TheLeanMeanC++Option parser is freestanding, you have to provide the means for
2682 * output in the first argument(s) to printUsage(). Because printUsage() is implemented as
2683 * a set of template functions, you have great flexibility in your choice of output
2684 * method. The following example demonstrates typical uses. Anything that's similar enough
2685 * will work.
2686 *
2687 * @code
2688 * #include <unistd.h> // write()
2689 * #include <iostream> // cout
2690 * #include <sstream> // ostringstream
2691 * #include <cstdio> // fwrite()
2692 * using namespace std;
2693 *
2694 * void my_write(const char* str, int size) {
2695 * fwrite(str, size, 1, stdout);
2696 * }
2697 *
2698 * struct MyWriter {
2699 * void write(const char* buf, size_t size) const {
2700 * fwrite(str, size, 1, stdout);
2701 * }
2702 * };
2703 *
2704 * struct MyWriteFunctor {
2705 * void operator()(const char* buf, size_t size) {
2706 * fwrite(str, size, 1, stdout);
2707 * }
2708 * };
2709 * ...
2710 * printUsage(my_write, usage); // custom write function
2711 * printUsage(MyWriter(), usage); // temporary of a custom class
2712 * MyWriter writer;
2713 * printUsage(writer, usage); // custom class object
2714 * MyWriteFunctor wfunctor;
2715 * printUsage(&wfunctor, usage); // custom functor
2716 * printUsage(write, 1, usage); // write() to file descriptor 1
2717 * printUsage(cout, usage); // an ostream&
2718 * printUsage(fwrite, stdout, usage); // fwrite() to stdout
2719 * ostringstream sstr;
2720 * printUsage(sstr, usage); // an ostringstream&
2721 *
2722 * @endcode
2723 *
2724 * @par Notes:
2725 * @li the @c write() method of a class that is to be passed as a temporary
2726 * as @c MyWriter() is in the example, must be a @c const method, because
2727 * temporary objects are passed as const reference. This only applies to
2728 * temporary objects that are created and destroyed in the same statement.
2729 * If you create an object like @c writer in the example, this restriction
2730 * does not apply.
2731 * @li a functor like @c MyWriteFunctor in the example must be passed as a pointer.
2732 * This differs from the way functors are passed to e.g. the STL algorithms.
2733 * @li All printUsage() templates are tiny wrappers around a shared non-template implementation.
2734 * So there's no penalty for using different versions in the same program.
2735 * @li printUsage() always interprets Descriptor::help as UTF-8 and always produces UTF-8-encoded
2736 * output. If your system uses a different charset, you must do your own conversion. You
2737 * may also need to change the font of the console to see non-ASCII characters properly.
2738 * This is particularly true for Windows.
2739 * @li @b Security @b warning: Do not insert untrusted strings (such as user-supplied arguments)
2740 * into the usage. printUsage() has no protection against malicious UTF-8 sequences.
2741 *
2742 * @param prn The output method to use. See the examples above.
2743 * @param usage the Descriptor[] array whose @c help texts will be formatted.
2744 * @param width the maximum number of characters per output line. Note that this number is
2745 * in actual characters, not bytes. printUsage() supports UTF-8 in @c help and will
2746 * count multi-byte UTF-8 sequences properly. Asian wide characters are counted
2747 * as 2 characters.
2748 * @param last_column_min_percent (0-100) The minimum percentage of @c width that should be available
2749 * for the last column (which typically contains the textual explanation of an option).
2750 * If less space is available, the last column will be printed on its own line, indented
2751 * according to @c last_column_own_line_max_percent.
2752 * @param last_column_own_line_max_percent (0-100) If the last column is printed on its own line due to
2753 * less than @c last_column_min_percent of the width being available, then only
2754 * @c last_column_own_line_max_percent of the extra line(s) will be used for the
2755 * last column's text. This ensures an indentation. See example below.
2756 *
2757 * @code
2758 * // width=20, last_column_min_percent=50 (i.e. last col. min. width=10)
2759 * --3456789 1234567890
2760 * 1234567890
2761 *
2762 * // width=20, last_column_min_percent=75 (i.e. last col. min. width=15)
2763 * // last_column_own_line_max_percent=75
2764 * --3456789
2765 * 123456789012345
2766 * 67890
2767 *
2768 * // width=20, last_column_min_percent=75 (i.e. last col. min. width=15)
2769 * // last_column_own_line_max_percent=33 (i.e. max. 5)
2770 * --3456789
2771 * 12345
2772 * 67890
2773 * 12345
2774 * 67890
2775 * @endcode
2776 */
2777 template<typename OStream>
2778 void printUsage(OStream& prn, const Descriptor usage[], int width = 80, int last_column_min_percent = 50,
2779 int last_column_own_line_max_percent = 75)
2780 {
2781 PrintUsageImplementation::OStreamWriter<OStream> write(prn);
2782 PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent);
2783 }
2784
2785 template<typename Function>
2786 void printUsage(Function* prn, const Descriptor usage[], int width = 80, int last_column_min_percent = 50,
2787 int last_column_own_line_max_percent = 75)
2788 {
2789 PrintUsageImplementation::FunctionWriter<Function> write(prn);
2790 PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent);
2791 }
2792
2793 template<typename Temporary>
2794 void printUsage(const Temporary& prn, const Descriptor usage[], int width = 80, int last_column_min_percent = 50,
2795 int last_column_own_line_max_percent = 75)
2796 {
2797 PrintUsageImplementation::TemporaryWriter<Temporary> write(prn);
2798 PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent);
2799 }
2800
2801 template<typename Syscall>
2802 void printUsage(Syscall* prn, int fd, const Descriptor usage[], int width = 80, int last_column_min_percent = 50,
2803 int last_column_own_line_max_percent = 75)
2804 {
2805 PrintUsageImplementation::SyscallWriter<Syscall> write(prn, fd);
2806 PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent);
2807 }
2808
2809 template<typename Function, typename Stream>
2810 void printUsage(Function* prn, Stream* stream, const Descriptor usage[], int width = 80, int last_column_min_percent =
2811 50,
2812 int last_column_own_line_max_percent = 75)
2813 {
2814 PrintUsageImplementation::StreamWriter<Function, Stream> write(prn, stream);
2815 PrintUsageImplementation::printUsage(write, usage, width, last_column_min_percent, last_column_own_line_max_percent);
2816 }
2817
2818 }
2819 // namespace option
2820
2821 #endif /* OPTIONPARSER_H_ */