- Display mutually exclusive arguments as ``[[-a]|[-b]]`` in usage
- Add ... trailer to repeatable arguments in usage: ``[-x]...``
- Implement the following enhancements:
By default usage is reported on a single line.
The ``ArgumentParser::set_usage_max_line_width(width)`` method can be used
to display the usage() on multiple lines, by defining the maximum line width.
It can be combined with a call to ``ArgumentParser::set_usage_break_on_mutex()``
to ask grouped mutually exclusive arguments to be displayed on a separate line.
``ArgumentParser::add_usage_newline()`` can also be used to force the next
argument to be displayed on a new line in the usage output.
The following snippet
```cpp
argparse::ArgumentParser program("program");
program.set_usage_max_line_width(80);
program.set_usage_break_on_mutex();
program.add_argument("--quite-long-option-name").flag();
auto &group = program.add_mutually_exclusive_group();
group.add_argument("-a").flag();
group.add_argument("-b").flag();
program.add_argument("-c").flag();
program.add_argument("--another-one").flag();
program.add_argument("-d").flag();
program.add_argument("--yet-another-long-one").flag();
program.add_argument("--will-go-on-new-line").flag();
program.add_usage_newline();
program.add_argument("--new-line").flag();
std::cout << program.usage() << std::endl;
```
will display:
```console
Usage: program [--help] [--version] [--quite-long-option-name]
[[-a]|[-b]]
[-c] [--another-one] [-d] [--yet-another-long-one]
[--will-go-on-new-line]
[--new-line]
```
Furthermore arguments can be separated into several groups by calling
``ArgumentParser::add_group(group_name)``. Only optional arguments should
be specified after the first call to add_group().
```cpp
argparse::ArgumentParser program("program");
program.set_usage_max_line_width(80);
program.add_argument("-a").flag().help("help_a");
program.add_group("Advanced options");
program.add_argument("-b").flag().help("help_b");
```
will display:
```console
Usage: program [--help] [--version] [-a]
Advanced options:
[-b]
```
Both changes are needed in the special case of GDAL where our existing
hand-made argument parser accepts positional arguments placed anywhere
in the arguments, not just after optional arguments.
In the GDAL code, in 8bb3455eed (diff-4592e7daae8543536dbeadf05a3c110282ea0fc089216186138c923a0d4d8000R170) ,
I've implemented a preliminary pass before calling
ArgumentParser::process_args() that re-order arguments. For that, I need
to be able to call consume() but without side-effects (dry_run=False)
and accept members that are private
It is possible to bind arguments to a variable storing their value, as an
alternative to explicitly calling ``program.get<T>(arg_name)`` or ``program[arg_name]``
This is currently implementeted for variables of type ``bool`` (this also
implicitly calls ``flag()``), ``int``, ``double``, ``std::string`` and
``std::vector<std::string>``. If the argument is not specified in the command
line, the default value (if set) is set into the variable.
```cpp
bool flagvar = false;
program.add_argument("--flagvar").store_into(flagvar);
int intvar = 0;
program.add_argument("--intvar").store_into(intvar);
double doublevar = 0;
program.add_argument("--doublevar").store_into(doublevar);
std::string strvar;
program.add_argument("--strvar").store_into(strvar);
std::vector<std::string> strvar_repeated;
program.add_argument("--strvar-repeated").append().store_into(strvar_repeated);
std::vector<std::string> strvar_multi_valued;
program.add_argument("--strvar-multi-valued").nargs(2).store_into(strvar_multi_valued);
```
It is sometimes desirable to offer an alias for an argument, but without it
appearing it in the usage. For example, to phase out a deprecated wording of
an argument while not breaking backwards compatible. This can be done with
the ``ArgumentParser::add_hidden_alias_for()` method.
```cpp
argparse::ArgumentParser program("test");
auto &arg = program.add_argument("--suppress").flag();
program.add_hidden_alias_for(arg, "--supress"); // old misspelled alias
```
The standard strtof/strtod/strtold are by default locale-aware. There
are a number of situations where we'd rather want to be able to use
locale-independent parsing functions. This can be done by setting the
ARGPARSE_CUSTOM_STRTOF/ARGPARSE_CUSTOM_STRTOD/ARGPARSE_CUSTOM_STRTOLD
macros to the appropriate value.
