166 lines
5.3 KiB
Markdown
166 lines
5.3 KiB
Markdown
[](https://travis-ci.org/jarro2783/cxxopts)
|
|
|
|
# Release versions
|
|
|
|
Note that `master` is generally a work in progress, and you probably want to use a
|
|
tagged release version.
|
|
|
|
# Quick start
|
|
|
|
This is a lightweight C++ option parser library, supporting the standard GNU
|
|
style syntax for options.
|
|
|
|
Options can be given as:
|
|
|
|
--long
|
|
--long=argument
|
|
--long argument
|
|
-a
|
|
-ab
|
|
-abc argument
|
|
|
|
where c takes an argument, but a and b do not.
|
|
|
|
Additionally, anything after `--` will be parsed as a positional argument.
|
|
|
|
## Basics
|
|
|
|
#include <cxxopts.hpp>
|
|
|
|
Create a cxxopts::Options instance.
|
|
|
|
cxxopts::Options options("MyProgram", "One line description of MyProgram");
|
|
|
|
Then use `add_options`.
|
|
|
|
options.add_options()
|
|
("d,debug", "Enable debugging")
|
|
("f,file", "File name", cxxopts::value<std::string>())
|
|
;
|
|
|
|
Options are declared with a long and an optional short option. A description
|
|
must be provided. The third argument is the value, if omitted it is boolean.
|
|
Any type can be given as long as it can be parsed, with operator>>.
|
|
|
|
To parse the command line do:
|
|
|
|
auto result = options.parse(argc, argv);
|
|
|
|
To retrieve an option use `result.count("option")` to get the number of times
|
|
it appeared, and
|
|
|
|
result["opt"].as<type>()
|
|
|
|
to get its value. If "opt" doesn't exist, or isn't of the right type, then an
|
|
exception will be thrown.
|
|
|
|
Note that the result of `options.parse` should only be used as long as the
|
|
`options` object that created it is in scope.
|
|
|
|
## Exceptions
|
|
|
|
Exceptional situations throw C++ exceptions. There are two types of
|
|
exceptions: errors defining the options, and errors when parsing a list of
|
|
arguments. All exceptions derive from `cxxopts::OptionException`. Errors
|
|
defining options derive from `cxxopts::OptionSpecException` and errors
|
|
parsing arguments derive from `cxxopts::OptionParseException`.
|
|
|
|
All exceptions define a `what()` function to get a printable string
|
|
explaining the error.
|
|
|
|
## Help groups
|
|
|
|
Options can be placed into groups for the purposes of displaying help messages.
|
|
To place options in a group, pass the group as a string to `add_options`. Then,
|
|
when displaying the help, pass the groups that you would like displayed as a
|
|
vector to the `help` function.
|
|
|
|
## Positional Arguments
|
|
|
|
Positional arguments can be optionally parsed into one or more options.
|
|
To set up positional arguments, call
|
|
|
|
options.parse_positional({"first", "second", "last"})
|
|
|
|
where "last" should be the name of an option with a container type, and the
|
|
others should have a single value.
|
|
|
|
## Default and implicit values
|
|
|
|
An option can be declared with a default or an implicit value, or both.
|
|
|
|
A default value is the value that an option takes when it is not specified
|
|
on the command line. The following specifies a default value for an option:
|
|
|
|
cxxopts::value<std::string>()->default_value("value")
|
|
|
|
An implicit value is the value that an option takes when it is given on the
|
|
command line without an argument. The following specifies an implicit value:
|
|
|
|
cxxopts::value<std::string>()->implicit_value("implicit")
|
|
|
|
If an option had both, then not specifying it would give the value `"value"`,
|
|
writing it on the command line as `--option` would give the value `"implicit"`,
|
|
and writing `--option=another` would give it the value `"another"`.
|
|
|
|
Note that the default and implicit value is always stored as a string,
|
|
regardless of the type that you want to store it in. It will be parsed as
|
|
though it was given on the command line.
|
|
|
|
## Boolean values
|
|
|
|
Boolean options have a default implicit value of `"true"`, which can be
|
|
overridden. The effect is that writing `-o` by itself will set option `o` to
|
|
`true`. However, they can also be written with various strings using `=value`.
|
|
There is no way to disambiguate positional arguments from the value following
|
|
a boolean, so we have chosen that they will be positional arguments, and
|
|
therefore, `-o false` does not work.
|
|
|
|
## Custom help
|
|
|
|
The string after the program name on the first line of the help can be
|
|
completely replaced by calling `options.custom_help`. Note that you might
|
|
also want to override the positional help by calling `options.positional_help`.
|
|
|
|
# Linking
|
|
|
|
This is a header only library.
|
|
|
|
# Requirements
|
|
|
|
The only build requirement is a C++ compiler that supports C++11 regular
|
|
expressions. For example GCC >= 4.9 or clang with libc++.
|
|
|
|
# Details
|
|
|
|
## Unknown options
|
|
|
|
In default mode all passed options to the CLI needs to be defined. Else an `option_not_exists_exception`
|
|
is thrown. This behavior can be disabled by allowing unrecognised options:
|
|
|
|
~~~
|
|
options.allow_unrecognised_options()
|
|
~~~
|
|
|
|
## Processing/Consuming of options
|
|
|
|
The command to parse the CLI arguments that usually looks similar to:
|
|
|
|
~~~
|
|
options.parse(argc, argv);
|
|
~~~
|
|
|
|
Does not only read `argc` and `argv` but also does manipulate the array behind those variables.
|
|
There are different parts of this behavior:
|
|
|
|
* All arguments that are recognized are consumed and therefore removed from the C-string array.
|
|
* All consumed arguments can be retrieved by: `result.arguments();`
|
|
* The only element in the array that is always preserved is
|
|
the `argv[0]` which represents the program name.
|
|
* In default mode all passed arguments have to be consumed.
|
|
See `allow_unrecognised_options()` to disable this behavior.
|
|
|
|
# TODO list
|
|
|
|
* None
|