Logo ROOT  
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_ */
ROOT::option::Parser::StoreOptionAction::parser
Parser & parser
Definition: OptionParser.h:1441
c
#define c(i)
Definition: RSha256.hxx:119
ROOT::option::PrintUsageImplementation::LineWrapper::process
void process(IStringWriter &write, const char *data, int len)
Process, wrap and output the next piece of data.
Definition: OptionParser.h:2338
ROOT::option::PrintUsageImplementation::SyscallWriter::operator()
virtual void operator()(const char *str, int size)
Writes the given number of chars beginning at the given pointer somewhere.
Definition: OptionParser.h:1802
ROOT::option::PrintUsageImplementation::LineWrapper::flush
void flush(IStringWriter &write)
Writes out all remaining data from the LineWrapper using write.
Definition: OptionParser.h:2308
ROOT::option::PrintUsageImplementation::LinePartIterator::restartTable
void restartTable()
Reset iteration to the beginning of the current table.
Definition: OptionParser.h:2014
ROOT::option::PrintUsageImplementation::OStreamWriter::ostream
OStream & ostream
Definition: OptionParser.h:1756
ROOT::option::Parser::parse
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.
Definition: OptionParser.h:1500
ROOT::option::Parser::nonop_args
const char ** nonop_args
Definition: OptionParser.h:1065
ROOT::option::Parser::StoreOptionAction::options
Option * options
Definition: OptionParser.h:1442
f
#define f(i)
Definition: RSha256.hxx:122
ROOT::option::PrintUsageImplementation::LinePartIterator
Definition: OptionParser.h:1937
ROOT::option::PrintUsageImplementation::FunctionWriter
Definition: OptionParser.h:1733
ROOT::option::Parser::shift
static void shift(const char **args, int count)
Definition: OptionParser.h:1358
ROOT::option::Option::isTagged
static bool isTagged(Option *ptr)
Definition: OptionParser.h:844
ROOT::option::Option::Option
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
ROOT::option::PrintUsageImplementation::LineWrapper::buf_full
bool buf_full()
Definition: OptionParser.h:2251
_
#define _(A, B)
Definition: cfortran.h:108
ROOT::option::ARG_ILLEGAL
@ ARG_ILLEGAL
The argument is not acceptable and that's fatal.
Definition: OptionParser.h:271
ROOT::option::Parser::streq
static bool streq(const char *st1, const char *st2)
Definition: OptionParser.h:1296
ROOT::option::PrintUsageImplementation::LineWrapper
Definition: OptionParser.h:2212
ROOT::option::PrintUsageImplementation::LinePartIterator::restartRow
void restartRow()
Reset iteration to the beginning of the current row.
Definition: OptionParser.h:2057
ROOT::option::Option::prev
Option * prev()
Returns a pointer to the previous element of the linked list or NULL if called on first().
Definition: OptionParser.h:656
ROOT::option::ARG_IGNORE
@ ARG_IGNORE
The argument is not acceptable but that's non-fatal because the option's argument is optional.
Definition: OptionParser.h:269
ROOT::option::PrintUsageImplementation::LinePartIterator::data
const char * data()
Returns the current part of the iteration.
Definition: OptionParser.h:2182
ROOT::option::Option::init
void init(const Descriptor *desc_, const char *name_, const char *arg_)
Definition: OptionParser.h:817
ROOT::option::PrintUsageImplementation::SyscallWriter
Definition: OptionParser.h:1797
ROOT::option::Parser::StoreOptionAction::perform
bool perform(Option &option)
Called by Parser::workhorse() for each Option that has been successfully parsed (including unknown op...
Definition: OptionParser.h:1465
ROOT::option::FullArg::Unknown
static option::ArgStatus Unknown(const option::Option &option, bool msg)
Definition: OptionParser.h:2847
ROOT::option::PrintUsageImplementation::IStringWriter::~IStringWriter
virtual ~IStringWriter()=default
ROOT::option::PrintUsageImplementation::printUsage
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)
Definition: OptionParser.h:2434
ROOT::option::ARG_NONE
@ ARG_NONE
The option does not take an argument.
Definition: OptionParser.h:265
ROOT::option::PrintUsageImplementation::LineWrapper::output
void output(IStringWriter &write, const char *data, int len)
Writes (data,len) into the ring buffer.
Definition: OptionParser.h:2273
ROOT::option::Stats::Stats
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
ROOT::option::PrintUsageImplementation::SyscallWriter::SyscallWriter
SyscallWriter(Syscall *w, int f)
Definition: OptionParser.h:1807
ROOT::option::PrintUsageImplementation::LinePartIterator::hit_target_line
bool hit_target_line
Flag whether we encountered a part with line index target_line_in_block in the current cell.
Definition: OptionParser.h:1949
ROOT::option::PrintUsageImplementation::LineWrapper::buf_next
void buf_next()
Call BEFORE reading ...buf[tail].
Definition: OptionParser.h:2264
ROOT::option::PrintUsageImplementation::LinePartIterator::col
int col
Index of current column.
Definition: OptionParser.h:1943
ROOT::option::PrintUsageImplementation::LineWrapper::wrote_something
bool wrote_something
Multiple methods of LineWrapper may decide to flush part of the buffer to free up space.
Definition: OptionParser.h:2244
ROOT::option::Arg::None
static ArgStatus None(const Option &, bool)
For options that don't take an argument: Returns ARG_NONE.
Definition: OptionParser.h:907
ROOT::option::Stats::CountOptionsAction::buffer_max
unsigned * buffer_max
Definition: OptionParser.h:1414
ROOT::option::PrintUsageImplementation::FunctionWriter::operator()
virtual void operator()(const char *str, int size)
Writes the given number of chars beginning at the given pointer somewhere.
Definition: OptionParser.h:1737
ROOT::option::Option::arg
const char * arg
Pointer to this Option's argument (if any).
Definition: OptionParser.h:500
ROOT::option::PrintUsageImplementation::LinePartIterator::update_length
void update_length()
Determines the byte and character lengths of the part at ptr and stores them in len and screenlen res...
Definition: OptionParser.h:1955
ROOT::option::Stats::options_max
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
ROOT::option::Option::nextwrap
Option * nextwrap()
Returns a pointer to the next element of the linked list with wrap-around from last() to first().
Definition: OptionParser.h:695
ROOT::option::Option::desc
const Descriptor * desc
Pointer to this Option's Descriptor.
Definition: OptionParser.h:476
ROOT::option::PrintUsageImplementation::LineWrapper::buf_store
void buf_store(const char *data, int len)
Definition: OptionParser.h:2256
width
include TDocParser_001 C image html pict1_TDocParser_001 png width
Definition: TDocParser.cxx:121
ROOT::option::Option::append
void append(Option *new_last)
Makes new_last the new last() by chaining it into the list after last().
Definition: OptionParser.h:710
ROOT::option::Stats::add
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.
Definition: OptionParser.h:1032
TGeant4Unit::s
static constexpr double s
Definition: TGeant4SystemOfUnits.h:168
ROOT::option::PrintUsageImplementation::StreamWriter::StreamWriter
StreamWriter(Function *w, Stream *s)
Definition: OptionParser.h:1828
ROOT::option::Descriptor::index
const unsigned index
Index of this option's linked list in the array filled in by the parser.
Definition: OptionParser.h:347
ROOT::option::PrintUsageImplementation::LinePartIterator::nextRow
bool nextRow()
Moves iteration to the next row (if any).
Definition: OptionParser.h:2026
ROOT::option::PrintUsageImplementation::LineWrapper::write_one_line
void write_one_line(IStringWriter &write)
Writes a single line of output from the buffer to write.
Definition: OptionParser.h:2284
ROOT::option::PrintUsageImplementation::LinePartIterator::ptr
const char * ptr
Ptr to current part within the current row.
Definition: OptionParser.h:1942
ROOT::option::Option::prev_
Option * prev_
Definition: OptionParser.h:456
x
Double_t x[n]
Definition: legend1.C:17
ROOT::option::Stats::Stats
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
ROOT::option::Option::first
Option * first()
Returns a pointer to the first element of the linked list.
Definition: OptionParser.h:619
ROOT::option::Stats
Determines the minimum lengths of the buffer and options arrays used for Parser.
Definition: OptionParser.h:931
ROOT::option::PrintUsageImplementation::TemporaryWriter::operator()
virtual void operator()(const char *str, int size)
Writes the given number of chars beginning at the given pointer somewhere.
Definition: OptionParser.h:1779
long
long
Definition: Converters.cxx:858
ROOT::option::Stats::CountOptionsAction
Definition: OptionParser.h:1412
ROOT::option::Parser::StoreOptionAction::StoreOptionAction
StoreOptionAction(Parser &parser_, Option options_[], Option buffer_[], int bufmax_)
Number of slots in buffer. -1 means "large enough".
Definition: OptionParser.h:1453
ROOT::option::PrintUsageImplementation::OStreamWriter::operator()
virtual void operator()(const char *str, int size)
Writes the given number of chars beginning at the given pointer somewhere.
Definition: OptionParser.h:1758
ROOT::option::PrintUsageImplementation::LineWrapper::x
int x
The indentation of the column to which the LineBuffer outputs.
Definition: OptionParser.h:2229
ROOT::option::Option::isFirst
bool isFirst() const
Returns true iff this is the first element of the linked list.
Definition: OptionParser.h:590
Function
Double_t(* Function)(Double_t)
Definition: Functor.C:4
ROOT::option::Parser::nonOptionsCount
int nonOptionsCount()
Returns the number of non-option arguments that remained at the end of the most recent parse() that a...
Definition: OptionParser.h:1220
ROOT::option::ARG_OK
@ ARG_OK
The argument is acceptable for the option.
Definition: OptionParser.h:267
ROOT::option::Descriptor::shortopt
const char *const shortopt
Each char in this string will be accepted as a short option character.
Definition: OptionParser.h:369
ROOT::option::PrintUsageImplementation::upmax
static void upmax(int &i1, int i2)
Definition: OptionParser.h:1838
ROOT::option::Parser::Action::perform
virtual bool perform(Option &)
Called by Parser::workhorse() for each Option that has been successfully parsed (including unknown op...
Definition: OptionParser.h:1384
ROOT::option::ArgStatus
ArgStatus
Possible results when checking if an argument is valid for a certain option.
Definition: OptionParser.h:262
ROOT::option::PrintUsageImplementation::LineWrapper::width
int width
The width of the column to line wrap.
Definition: OptionParser.h:2233
ROOT::option::Descriptor::longopt
const char *const longopt
The long option name (without the leading – ).
Definition: OptionParser.h:404
ROOT::option::PrintUsageImplementation::LineWrapper::datbuf
const char * datbuf[bufmask+1]
Ring buffer for data component of pair (data, length).
Definition: OptionParser.h:2222
ROOT::option::PrintUsageImplementation::StreamWriter
Definition: OptionParser.h:1818
ROOT::option::Option
A parsed option from the command line together with its argument if it has one.
Definition: OptionParser.h:453
ROOT::option::Parser::Parser
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.
Definition: OptionParser.h:1105
ROOT::option::Option::tag
static Option * tag(Option *ptr)
Definition: OptionParser.h:834
ROOT::option::Parser::op_count
int op_count
Definition: OptionParser.h:1063
x1
static const double x1[5]
Definition: RooGaussKronrodIntegrator1D.cxx:346
ROOT::option::PrintUsageImplementation::LineWrapper::tail
int tail
index for next read - 1 (i.e.
Definition: OptionParser.h:2235
ROOT::option::PrintUsageImplementation::OStreamWriter
Definition: OptionParser.h:1754
ROOT::option::PrintUsageImplementation::isWideChar
static bool isWideChar(unsigned ch)
Returns true if ch is the unicode code point of a wide character.
Definition: OptionParser.h:1890
ROOT::option::PrintUsageImplementation::LinePartIterator::next
bool next()
Moves iteration to the next part (if any).
Definition: OptionParser.h:2076
ROOT::option::PrintUsageImplementation::LineWrapper::LineWrapper
LineWrapper(int x1, int x2)
Constructs a LineWrapper that wraps its output to fit into screen columns x1 (incl....
Definition: OptionParser.h:2421
ROOT::option::PrintUsageImplementation::LinePartIterator::nextTable
bool nextTable()
Moves iteration to the next table (if any).
Definition: OptionParser.h:1993
ROOT::option::Parser::streqabbr
static bool streqabbr(const char *st1, const char *st2, long long min)
Definition: OptionParser.h:1328
ROOT::option::Stats::CountOptionsAction::perform
bool perform(Option &)
Called by Parser::workhorse() for each Option that has been successfully parsed (including unknown op...
Definition: OptionParser.h:1425
ROOT::option::PrintUsageImplementation::SyscallWriter::write
Syscall * write
Definition: OptionParser.h:1799
ROOT::option::Stats::Stats
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
ROOT::option::PrintUsageImplementation::FunctionWriter::write
Function * write
Definition: OptionParser.h:1735
ROOT::option::Option::index
int index() const
Returns Descriptor::index of this Option's Descriptor, or -1 if this Option is invalid (unused).
Definition: OptionParser.h:553
ROOT::option::PrintUsageImplementation::LineWrapper::lenbuf
int lenbuf[bufmask+1]
Ring buffer for length component of pair (data, length).
Definition: OptionParser.h:2218
ROOT::option::Parser::parse
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).
Definition: OptionParser.h:1179
ROOT::option::Stats::CountOptionsAction::CountOptionsAction
CountOptionsAction(unsigned *buffer_max_)
Creates a new CountOptionsAction that will increase *buffer_max_ for each parsed Option.
Definition: OptionParser.h:1420
ROOT::option::PrintUsageImplementation::TemporaryWriter::TemporaryWriter
TemporaryWriter(const Temporary &u)
Definition: OptionParser.h:1784
ROOT::option::Parser::instr
static bool instr(char ch, const char *st)
Definition: OptionParser.h:1346
ROOT::option::Option::namelen
int namelen
The length of the option name.
Definition: OptionParser.h:521
ROOT::option::Option::isLast
bool isLast() const
Returns true iff this is the last element of the linked list.
Definition: OptionParser.h:603
ROOT::option::Parser::optionsCount
int optionsCount()
Returns the number of valid Option objects in buffer[].
Definition: OptionParser.h:1201
ROOT::option::PrintUsageImplementation::LinePartIterator::tablestart
const Descriptor * tablestart
The 1st descriptor of the current table.
Definition: OptionParser.h:1939
ROOT::option::PrintUsageImplementation::LinePartIterator::max_line_in_block
int max_line_in_block
Greatest index of a line within the block.
Definition: OptionParser.h:1946
ROOT::option::Option::prevwrap
Option * prevwrap()
Returns a pointer to the previous element of the linked list with wrap-around from first() to last().
Definition: OptionParser.h:669
ROOT::option::PrintUsageImplementation::LineWrapper::buf_empty
bool buf_empty()
Definition: OptionParser.h:2246
ROOT::option::Parser::Parser
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).
Definition: OptionParser.h:1097
ROOT::option::Option::operator=
Option & operator=(const Option &orig)
Makes *this a copy of orig except for the linked list pointers.
Definition: OptionParser.h:792
ROOT::option::Stats::Stats
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
ROOT::option::Parser::Action
Definition: OptionParser.h:1374
ROOT::option::PrintUsageImplementation::StreamWriter::fwrite
Function * fwrite
Definition: OptionParser.h:1820
ROOT::option::PrintUsageImplementation::FunctionWriter::FunctionWriter
FunctionWriter(Function *w)
Definition: OptionParser.h:1742
ROOT::option::PrintUsageImplementation::LineWrapper::bufmask
static const int bufmask
Must be a power of 2 minus 1.
Definition: OptionParser.h:2214
ROOT::option::Parser
Checks argument vectors for validity and parses them into data structures that are easier to work wit...
Definition: OptionParser.h:1061
ROOT::option::PrintUsageImplementation::StreamWriter::stream
Stream * stream
Definition: OptionParser.h:1821
ROOT::option::Option::Option
Option(const Option &orig)
Makes *this a copy of orig except for the linked list pointers.
Definition: OptionParser.h:803
ROOT::option::PrintUsageImplementation::LinePartIterator::line_in_block
int line_in_block
Line index within the current cell of the current part.
Definition: OptionParser.h:1947
ROOT::option::Parser::nonop_count
int nonop_count
Definition: OptionParser.h:1064
ROOT::option::PrintUsageImplementation::TemporaryWriter::userstream
const Temporary & userstream
Definition: OptionParser.h:1777
ROOT::option::Stats::Stats
Stats()
Creates a Stats object with counts set to 1 (for the sentinel element).
Definition: OptionParser.h:960
ROOT::option::Stats::add
void add(const Descriptor usage[], int argc, const char **argv, int min_abbr_len=0, bool single_minus_longopt=false)
POSIX add() (gnu==false).
Definition: OptionParser.h:1025
ROOT::option::PrintUsageImplementation::LinePartIterator::screenlen
int screenlen
Length of the current part in screen columns (taking narrow/wide chars into account).
Definition: OptionParser.h:1945
ROOT::option::PrintUsageImplementation::LinePartIterator::target_line_in_block
int target_line_in_block
Line index of the parts we should return to the user on this iteration.
Definition: OptionParser.h:1948
ROOT::option::Parser::nonOptions
const char ** nonOptions()
Returns a pointer to an array of non-option arguments (only valid if nonOptionsCount() >0 ).
Definition: OptionParser.h:1236
ROOT::option::PrintUsageImplementation::LinePartIterator::rowdesc
const Descriptor * rowdesc
The Descriptor that contains the current row.
Definition: OptionParser.h:1940
ROOT::option::Stats::add
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.
Definition: OptionParser.h:1507
ROOT::option::Option::count
int count()
Returns the number of times this Option (or others with the same Descriptor::index) occurs in the arg...
Definition: OptionParser.h:570
ROOT::option::Arg
Functions for checking the validity of option arguments.
Definition: OptionParser.h:904
ROOT::option::Option::next_
Option * next_
Definition: OptionParser.h:455
ROOT::option::Option::Option
Option()
Creates a new Option that is a one-element linked list and has NULL desc, name, arg and namelen.
Definition: OptionParser.h:766
ROOT::option::Parser::parse
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.
Definition: OptionParser.h:1172
void
typedef void((*Func_t)())
ROOT::option::Stats::buffer_max
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
ROOT::option::Parser::parse
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.
Definition: OptionParser.h:1186
ROOT::option::PrintUsageImplementation::OStreamWriter::OStreamWriter
OStreamWriter(OStream &o)
Definition: OptionParser.h:1763
ROOT::option::PrintUsageImplementation::indent
static void indent(IStringWriter &write, int &x, int want_x)
Definition: OptionParser.h:1854
ROOT::option::Parser::nonOption
const char * nonOption(int i)
Returns nonOptions()[i] (without checking if i is in range!).
Definition: OptionParser.h:1244
ROOT::option::PrintUsageImplementation::IStringWriter::operator()
virtual void operator()(const char *, int)
Writes the given number of chars beginning at the given pointer somewhere.
Definition: OptionParser.h:1720
ROOT::option::Option::type
int type() const
Returns Descriptor::type of this Option's Descriptor, or 0 if this Option is invalid (unused).
Definition: OptionParser.h:544
ROOT::option::Parser::error
bool error()
Returns true if an unrecoverable error occurred while parsing options.
Definition: OptionParser.h:1264
ROOT::option::PrintUsageImplementation::LineWrapper::head
int head
index for next write
Definition: OptionParser.h:2234
ROOT::option::FullArg::Numeric
static option::ArgStatus Numeric(const option::Option &option, bool msg)
Definition: OptionParser.h:2871
ROOT::option::Arg::Optional
static ArgStatus Optional(const Option &option, bool)
Returns ARG_OK if the argument is attached and ARG_IGNORE otherwise.
Definition: OptionParser.h:913
ROOT::option::Parser::Parser
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.
Definition: OptionParser.h:1089
ROOT::option::Option::name
const char * name
The name of the option as used on the command line.
Definition: OptionParser.h:492
ROOT::option::Descriptor
Describes an option, its help text (usage) and how it should be parsed.
Definition: OptionParser.h:326
ROOT::option::Parser::err
bool err
Definition: OptionParser.h:1066
ROOT::option::PrintUsageImplementation::IStringWriter
Definition: OptionParser.h:1715
ROOT::option::Parser::StoreOptionAction
Definition: OptionParser.h:1439
ROOT::option::printUsage
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.
Definition: OptionParser.h:2798
ROOT::option::Parser::StoreOptionAction::finished
bool finished(int numargs, const char **args)
Called by Parser::workhorse() after finishing the parse.
Definition: OptionParser.h:1485
ROOT::option::Descriptor::check_arg
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
ROOT::option::Parser::Action::~Action
virtual ~Action()=default
ROOT::option::Parser::Parser
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.
Definition: OptionParser.h:1081
ROOT::option::Parser::StoreOptionAction::bufmax
int bufmax
Definition: OptionParser.h:1444
ROOT::option::PrintUsageImplementation::LinePartIterator::screenLength
int screenLength()
Returns the width in screen columns of the part pointed to by data().
Definition: OptionParser.h:2174
ROOT::option::PrintUsageImplementation::LinePartIterator::length
int length()
Returns the length of the part pointed to by data() in raw chars (not UTF-8 characters).
Definition: OptionParser.h:2165
ROOT::option::Stats::add
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.
Definition: OptionParser.h:1018
ROOT::option::Descriptor::help
const char * help
The usage text associated with the options in this Descriptor.
Definition: OptionParser.h:433
x2
static const double x2[5]
Definition: RooGaussKronrodIntegrator1D.cxx:364
ROOT::option::Option::untag
static Option * untag(Option *ptr)
Definition: OptionParser.h:839
ROOT::option::CheckArg
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
ROOT::option::PrintUsageImplementation::LinePartIterator::LinePartIterator
LinePartIterator(const Descriptor usage[])
Creates an iterator for usage.
Definition: OptionParser.h:1982
ROOT::option::Option::next
Option * next()
Returns a pointer to the next element of the linked list or NULL if called on last().
Definition: OptionParser.h:682
ROOT::option::FullArg::printError
static void printError(const char *msg1, const option::Option &opt, const char *msg2)
Definition: OptionParser.h:2840
ROOT::option::FullArg::Required
static option::ArgStatus Required(const option::Option &option, bool msg)
Definition: OptionParser.h:2853
ROOT::option::Parser::workhorse
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)
Definition: OptionParser.h:1524
ROOT::option::PrintUsageImplementation::SyscallWriter::fd
int fd
Definition: OptionParser.h:1800
ROOT::option::Parser::Action::finished
virtual bool finished(int numargs, const char **args)
Called by Parser::workhorse() after finishing the parse.
Definition: OptionParser.h:1397
ROOT::option::FullArg::NonEmpty
static option::ArgStatus NonEmpty(const option::Option &option, bool msg)
Definition: OptionParser.h:2862
ROOT::option::PrintUsageImplementation::TemporaryWriter
Definition: OptionParser.h:1775
ROOT::option::Parser::Parser
Parser()
Creates a new Parser.
Definition: OptionParser.h:1072
ROOT::option::Option::last
Option * last()
Returns a pointer to the last element of the linked list.
Definition: OptionParser.h:643
ROOT::option::PrintUsageImplementation::StreamWriter::operator()
virtual void operator()(const char *str, int size)
Writes the given number of chars beginning at the given pointer somewhere.
Definition: OptionParser.h:1823
ROOT::option::PrintUsageImplementation::LinePartIterator::line
int line()
Returns the index (counting from 0) of the line within the current column this part belongs to.
Definition: OptionParser.h:2157
ROOT::option::PrintUsageImplementation::LinePartIterator::rowstart
const char * rowstart
Ptr to 1st character of current row within rowdesc->help.
Definition: OptionParser.h:1941
ROOT::option::PrintUsageImplementation::LinePartIterator::column
int column()
Returns the index (counting from 0) of the column in which the part pointed to by data() is located.
Definition: OptionParser.h:2148
ROOT
VSD Structures.
Definition: StringConv.hxx:21
ROOT::option::PrintUsageImplementation::LinePartIterator::len
int len
Length of the current part (that ptr points at) in BYTES.
Definition: OptionParser.h:1944
ROOT::option::FullArg
Definition: OptionParser.h:2838
ROOT::option::Descriptor::type
const int type
Used to distinguish between options with the same ROOT Reference Documentation.
Definition: OptionParser.h:356
ROOT::option::Parser::StoreOptionAction::buffer
Option * buffer
Definition: OptionParser.h:1443
ROOT::option::PrintUsageImplementation
Definition: OptionParser.h:1709