Logo ROOT   master
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 /*
41 Danio Piparo - Since we import this parser from tan external source, we keep
42 track of the changes:
43 
44 New Features 6-7-12:
45  o Added FullArg class from the examples in the header
46 
47 Bugs 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 
234 namespace ROOT {
235 /** @brief The namespace of The Lean Mean C++ Option Parser. */
236 namespace option
237 {
238 
239 #ifdef _MSC_VER
240 #include <intrin.h>
241 #pragma intrinsic(_BitScanReverse)
242 struct 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 
254 class 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.
272 };
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  */
302 typedef 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  */
453 class Option
454 {
457 public:
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  */
476  const Descriptor* desc;
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  */
521  int namelen;
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  */
766  Option() :
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 
808 private:
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  */
904 struct 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  */
931 struct 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  */
960  Stats() :
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  }
1037 private:
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  */
1061 class Parser
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()
1067 public:
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 
1269 private:
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;
1415 public:
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".
1445 public:
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 
1500 inline 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 
1507 inline 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 
1520  CountOptionsAction action(&buffer_max);
1521  Parser::workhorse(gnu, usage, argc, argv, action, single_minus_longopt, false, min_abbr_len);
1522 }
1523 
1524 inline 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.
1982  LinePartIterator(const Descriptor 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  */
1993  bool nextTable()
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  {
2016  rowdesc = tablestart;
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;
2043  rowstart = rowdesc->help;
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  */
2057  void restartRow()
2058  {
2059  ptr = rowstart;
2060  col = -1;
2061  len = 0;
2062  screenlen = 0;
2063  max_line_in_block = 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  */
2148  int column()
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  */
2165  int length()
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  */
2233  int width;
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 
2246  bool buf_empty()
2247  {
2248  return ((tail + 1) & bufmask) == head;
2249  }
2250 
2251  bool buf_full()
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].
2264  void buf_next()
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  */
2308  void flush(IStringWriter& write)
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  */
2797 template<typename OStream>
2798 void 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 
2805 template<typename Function>
2806 void 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 
2813 template<typename Temporary>
2814 void 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 
2821 template<typename Syscall>
2822 void 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 
2829 template<typename Function, typename Stream>
2830 void 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 
2838 struct 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_ */
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.
const char * datbuf[bufmask+1]
Ring buffer for data component of pair (data, length).
StoreOptionAction(Parser &parser_, Option options_[], Option buffer_[], int bufmax_)
Number of slots in buffer. -1 means "large enough".
virtual void operator()(const char *str, int size)
Writes the given number of chars beginning at the given pointer somewhere.
Option * nextwrap()
Returns a pointer to the next element of the linked list with wrap-around from last() to first()...
Definition: OptionParser.h:695
int width
The width of the column to line wrap.
virtual void operator()(const char *str, int size)
Writes the given number of chars beginning at the given pointer somewhere.
Option * next()
Returns a pointer to the next element of the linked list or NULL if called on last().
Definition: OptionParser.h:682
Parser()
Creates a new Parser.
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 output(IStringWriter &write, const char *data, int len)
Writes (data,len) into the ring buffer.
Returns the available number of logical cores.
Definition: StringConv.hxx:21
Option * prevwrap()
Returns a pointer to the previous element of the linked list with wrap-around from first() to last()...
Definition: OptionParser.h:669
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).
Option & operator=(const Option &orig)
Makes *this a copy of orig except for the linked list pointers.
Definition: OptionParser.h:792
static void upmax(int &i1, int i2)
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)
Functions for checking the validity of option arguments.
Definition: OptionParser.h:904
int max_line_in_block
Greatest index of a line within the block.
bool error()
Returns true if an unrecoverable error occurred while parsing options.
Option * last()
Returns a pointer to the last element of the linked list.
Definition: OptionParser.h:643
int count()
Returns the number of times this Option (or others with the same Descriptor::index) occurs in the arg...
Definition: OptionParser.h:570
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.
const int type
Used to distinguish between options with the same ROOT Reference Documentation.
Definition: OptionParser.h:356
int lenbuf[bufmask+1]
Ring buffer for length component of pair (data, length).
bool perform(Option &)
Called by Parser::workhorse() for each Option that has been successfully parsed (including unknown op...
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.
static option::ArgStatus Numeric(const option::Option &option, bool msg)
virtual bool perform(Option &)
Called by Parser::workhorse() for each Option that has been successfully parsed (including unknown op...
#define f(i)
Definition: RSha256.hxx:104
static Option * tag(Option *ptr)
Definition: OptionParser.h:834
static ArgStatus Optional(const Option &option, bool)
Returns ARG_OK if the argument is attached and ARG_IGNORE otherwise.
Definition: OptionParser.h:913
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
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
int screenLength()
Returns the width in screen columns of the part pointed to by data().
const unsigned index
Index of this option&#39;s linked list in the array filled in by the parser.
Definition: OptionParser.h:347
const Descriptor * rowdesc
The Descriptor that contains the current row.
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.
bool nextTable()
Moves iteration to the next table (if any).
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).
void restartRow()
Reset iteration to the beginning of the current row.
Option * prev()
Returns a pointer to the previous element of the linked list or NULL if called on first()...
Definition: OptionParser.h:656
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
int x
The indentation of the column to which the LineBuffer outputs.
virtual void operator()(const char *str, int size)
Writes the given number of chars beginning at the given pointer somewhere.
Checks argument vectors for validity and parses them into data structures that are easier to work wit...
Describes an option, its help text (usage) and how it should be parsed.
Definition: OptionParser.h:326
void add(const Descriptor usage[], int argc, const char **argv, int min_abbr_len=0, bool single_minus_longopt=false)
POSIX add() (gnu==false).
static bool streq(const char *st1, const char *st2)
static const double x2[5]
virtual void operator()(const char *str, int size)
Writes the given number of chars beginning at the given pointer somewhere.
Double_t x[n]
Definition: legend1.C:17
const char * ptr
Ptr to current part within the current row.
static Option * untag(Option *ptr)
Definition: OptionParser.h:839
bool hit_target_line
Flag whether we encountered a part with line index target_line_in_block in the current cell...
static void printError(const char *msg1, const option::Option &opt, const char *msg2)
const char * rowstart
Ptr to 1st character of current row within rowdesc->help.
virtual void operator()(const char *, int)
Writes the given number of chars beginning at the given pointer somewhere.
static option::ArgStatus Required(const option::Option &option, bool msg)
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)
const char *const longopt
The long option name (without the leading – ).
Definition: OptionParser.h:404
const char * arg
Pointer to this Option&#39;s argument (if any).
Definition: OptionParser.h:500
void process(IStringWriter &write, const char *data, int len)
Process, wrap and output the next piece of data.
bool perform(Option &option)
Called by Parser::workhorse() for each Option that has been successfully parsed (including unknown op...
static constexpr double s
int line_in_block
Line index within the current cell of the current part.
static bool isWideChar(unsigned ch)
Returns true if ch is the unicode code point of a wide character.
The option does not take an argument.
Definition: OptionParser.h:265
int screenlen
Length of the current part in screen columns (taking narrow/wide chars into account).
int line()
Returns the index (counting from 0) of the line within the current column this part belongs to...
LinePartIterator(const Descriptor usage[])
Creates an iterator for usage.
Option * first()
Returns a pointer to the first element of the linked list.
Definition: OptionParser.h:619
CountOptionsAction(unsigned *buffer_max_)
Creates a new CountOptionsAction that will increase *buffer_max_ for each parsed Option.
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.
virtual void operator()(const char *str, int size)
Writes the given number of chars beginning at the given pointer somewhere.
const char *const shortopt
Each char in this string will be accepted as a short option character.
Definition: OptionParser.h:369
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.
void update_length()
Determines the byte and character lengths of the part at ptr and stores them in len and screenlen res...
A parsed option from the command line together with its argument if it has one.
Definition: OptionParser.h:453
static void indent(IStringWriter &write, int &x, int want_x)
Double_t(* Function)(Double_t)
Definition: Functor.C:4
static option::ArgStatus NonEmpty(const option::Option &option, bool msg)
const Descriptor * tablestart
The 1st descriptor of the current table.
static void shift(const char **args, int count)
static bool isTagged(Option *ptr)
Definition: OptionParser.h:844
void init(const Descriptor *desc_, const char *name_, const char *arg_)
Definition: OptionParser.h:817
The argument is acceptable for the option.
Definition: OptionParser.h:267
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.
#define _(A, B)
Definition: cfortran.h:108
bool nextRow()
Moves iteration to the next row (if any).
virtual ~Action()=default
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
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
int index() const
Returns Descriptor::index of this Option&#39;s Descriptor, or -1 if this Option is invalid (unused)...
Definition: OptionParser.h:553
bool next()
Moves iteration to the next part (if any).
int column()
Returns the index (counting from 0) of the column in which the part pointed to by data() is located...
include TDocParser_001 C image html pict1_TDocParser_001 png width
Definition: TDocParser.cxx:120
The argument is not acceptable but that&#39;s non-fatal because the option&#39;s argument is optional...
Definition: OptionParser.h:269
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.
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
static const double x1[5]
void append(Option *new_last)
Makes new_last the new last() by chaining it into the list after last().
Definition: OptionParser.h:710
Determines the minimum lengths of the buffer and options arrays used for Parser.
Definition: OptionParser.h:931
static ArgStatus None(const Option &, bool)
For options that don&#39;t take an argument: Returns ARG_NONE.
Definition: OptionParser.h:907
bool isFirst() const
Returns true iff this is the first element of the linked list.
Definition: OptionParser.h:590
int length()
Returns the length of the part pointed to by data() in raw chars (not UTF-8 characters).
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
bool wrote_something
Multiple methods of LineWrapper may decide to flush part of the buffer to free up space...
void write_one_line(IStringWriter &write)
Writes a single line of output from the buffer to write.
Option(const Option &orig)
Makes *this a copy of orig except for the linked list pointers.
Definition: OptionParser.h:803
const Descriptor * desc
Pointer to this Option&#39;s Descriptor.
Definition: OptionParser.h:476
LineWrapper(int x1, int x2)
Constructs a LineWrapper that wraps its output to fit into screen columns x1 (incl.) to x2 (excl.).
void buf_next()
Call BEFORE reading ...buf[tail].
typedef void((*Func_t)())
virtual bool finished(int numargs, const char **args)
Called by Parser::workhorse() after finishing the parse.
const char ** nonOptions()
Returns a pointer to an array of non-option arguments (only valid if nonOptionsCount() >0 )...
const char * data()
Returns the current part of the iteration.
Stats()
Creates a Stats object with counts set to 1 (for the sentinel element).
Definition: OptionParser.h:960
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...
Option()
Creates a new Option that is a one-element linked list and has NULL desc, name, arg and namelen...
Definition: OptionParser.h:766
int len
Length of the current part (that ptr points at) in BYTES.
const char * help
The usage text associated with the options in this Descriptor.
Definition: OptionParser.h:433
const char ** nonop_args
#define c(i)
Definition: RSha256.hxx:101
const char * nonOption(int i)
Returns nonOptions()[i] (without checking if i is in range!).
int nonOptionsCount()
Returns the number of non-option arguments that remained at the end of the most recent parse() that a...
void flush(IStringWriter &write)
Writes out all remaining data from the LineWrapper using write.
static option::ArgStatus Unknown(const option::Option &option, bool msg)
int type() const
Returns Descriptor::type of this Option&#39;s Descriptor, or 0 if this Option is invalid (unused)...
Definition: OptionParser.h:544
static bool streqabbr(const char *st1, const char *st2, long long min)
int namelen
The length of the option name.
Definition: OptionParser.h:521
bool isLast() const
Returns true iff this is the last element of the linked list.
Definition: OptionParser.h:603
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.
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
const char * name
The name of the option as used on the command line.
Definition: OptionParser.h:492
bool finished(int numargs, const char **args)
Called by Parser::workhorse() after finishing the parse.
int target_line_in_block
Line index of the parts we should return to the user on this iteration.
int optionsCount()
Returns the number of valid Option objects in buffer[].
ArgStatus
Possible results when checking if an argument is valid for a certain option.
Definition: OptionParser.h:262
The argument is not acceptable and that&#39;s fatal.
Definition: OptionParser.h:271
static bool instr(char ch, const char *st)
static const int bufmask
Must be a power of 2 minus 1.
void restartTable()
Reset iteration to the beginning of the current table.