Lyra

A simple to use, composing, header only, command line arguments parser for C++ 11 and beyond.

Obtain
License
Standards
Stats
Tests

License

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)

Features

• Header only with no external dependencies (except the std library).

• Define your interface once to get parsing, type conversions and usage strings with no redundancy.

• Composing. Each opt or arg is 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.

Using

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.

More

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.