Also fixes the incompatibility between store_into and scan and action:
when the three methods above were called, being all based on the
(unique) action, the last one would overwrite the previous ones.
This issue was making the parser strictly dependant on the order
of the scan/store_into/action calls making them mutually exclusive.
The argparse.hpp copy inside GDAL has caused Coverity Scan to emit a
(false-positive) warning about x not being initialized.
```
________________________________________________________________________________________________________
*** CID 1544814: Uninitialized variables (UNINIT)
/gdal/apps/argparse/argparse.hpp: 257 in gdal_argparse::details::do_from_chars<unsigned char, (int)10>(std::basic_string_view<char, std::char_traits<char>>)()
251 if (ec == std::errc::invalid_argument) {
252 throw std::invalid_argument{"pattern '" + std::string(s) + "' not found"};
253 }
254 if (ec == std::errc::result_out_of_range) {
255 throw std::range_error{"'" + std::string(s) + "' not representable"};
256 }
>>> CID 1544814: Uninitialized variables (UNINIT)
>>> Using uninitialized value "x".
```
Let's initialize it to 0 to make the analyzer happy
- 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.