A simple to use, composing, header only, command line arguments parser for C++ 11 and beyond.
| Obtain |
|
| License |
|
| Standards |
|
| Stats |
|
| Tests |
|
Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
-
Header only with no external dependencies (except the
stdlibrary). -
Define your interface once to get parsing, type conversions and usage strings with no redundancy.
-
Composing. Each
optorargis an independent parser. Combine these to produce a composite parser — this can be done in stages across multiple function calls — or even projects. -
Bind parsers directly to variables that will receive the results of the parse — no intermediate dictionaries to worry about.
-
Or can also bind parsers to lambdas for more custom handling.
-
Deduces types from bound variables or lambdas and performs type conversions (via
ostream <<), with error handling, behind the scenes. -
Bind parsers to vectors for args that can have multiple values.
-
Uses result types for error propagation, rather than exceptions (doesn’t yet build with exceptions disabled, but that will be coming later)
-
Models POSIX standards for short and long opt behavior.
-
Customizable option syntax.
-
Specify cardinality of
arg-s from one to many. -
Limit option values to a specified set of values.
-
Recursive argument groups with callback for detection. This allows for easy and generic sub-command specifications.
To use, just #include <lyra/lyra.hpp>
A parser for a single option can be created like this:
int width = 0;
auto cli = lyra::cli()
| lyra::opt( width, "width" )
["-w"]["--width"]
("How wide should it be?");You can use this parser directly like this:
auto result = cli.parse( { argc, argv } );
if ( !result )
{
std::cerr << "Error in command line: " << result.message() << std::endl;
exit(1);
}
// Everything was ok, width will have a value if supplied on command line.Note that exceptions are not used for error handling.
You can combine parsers by composing with |, like this:
int width = 0;
std::string name;
bool doIt = false;
std::string command;
auto cli
= lyra::opt( width, "width" )
["-w"]["--width"]
("How wide should it be?")
| lyra::opt( name, "name" )
["-n"]["--name"]
("By what name should I be known")
| lyra::opt( doIt )
["-d"]["--doit"]
("Do the thing" )
| lyra::arg( command, "command" )
("which command to run");opt specifies options that start with a short dash (-) or long dash (--).
Options can be argument taking (such as -w 42), in which case
the opt takes a second argument — a hint, or they are pure flags (such as
-d), in which case the opt has only one argument — which must be a boolean.
The option names are provided in one or more sets of square brackets, and a
description string can be provided in parentheses. The first argument to an
opt is any variable, local, global member, of any type that can be converted
from a string using std::ostream.
arg specifies arguments that are not tied to options, and so have no square
bracket names. They otherwise work just like opt.
A usage string can be obtained by inserting the parser into a stream. The usage string is built from the information supplied.
As a convenience, the standard help options (-h, --help and -?) can be
specified using the help parser, which just takes a boolean to bind to.
There is a single-header version that is generated from the source files.
You can find it at data/single_include/lyra/lyra.hpp. Some caveats for it:
-
It’s not the preferred method of using the library.
-
It’s not thoroughly tested.
-
It’s intended for use cases like Compiler Explorer. Where it allows for immediate experimentation.
-
Support for it will not be a priority.
-
Hence prefer to use the regular multi-file sources in your projects.
For more information and documentation see the web site.