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