Home

Awesome

Clara v1.1.5

Build Status Build status codecov

!! This repository is unmaintained. Go here for a fork that is somewhat maintained. !!


A simple to use, composable, command line parser for C++ 11 and beyond.

Clara is a single-header library.

To use, just #include "clara.hpp"

A parser for a single option can be created like this:

int width = 0;
// ...
using namespace clara;
auto cli
    = Opt( width, "width" )
        ["-w"]["--width"]
        ("How wide should it be?");

You can use this parser directly like this:

auto result = cli.parse( Args( argc, argv ) );
if( !result ) {
    std::cerr << "Error in command line: " << result.errorMessage() << 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
    = Opt( width, "width" )
        ["-w"]["--width"]
        ("How wide should it be?")
    | Opt( name, "name" )
        ["-n"]["--name"]
        ("By what name should I be known")
    | Opt( doIt )
        ["-d"]["--doit"]
        ("Do the thing" )
    | Arg( command, "command" )
        ("which command to run");

Opts specify options that start with a short dash (-) or long dash (--). On Windows forward slashes are also accepted (and automatically interpretted as a short 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.

Args specify arguments that are not tied to options, and so have no square bracket names. They otherwise work just like Opts.

A, console optimised, usage string can be obtained by inserting the parser into a stream. The usage string is built from the information supplied and is formatted for the console width.

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.

For more usage please see the unit tests or look at how it is used in the Catch code-base (catch-lib.net). Fuller documentation will be coming soon.

Some of the key features:

Roadmap

To see which direction Clara is going in, please see the roadmap

Old version

If you used the earlier, v0.x, version of Clara please note that this is a complete rewrite which assumes C++11 and has a different interface (composability was a big step forward). Conversion between v0.x and v1.x is a fairly simple and mechanical task, but is a bit of manual work - so don't take this version until you're ready (and, of course, able to use C++11).

I hope you'll find the new interface an improvement - and this will be built on to offer new features moving forwards. I don't expect to maintain v0.x any further, but it remains on a branch.