1. Introduction

Lyra is a simple to use, composing, command line parser for C++ 11 and beyond. It provides easy to use command line parsing for most use cases with a minimal source footprint. It doesn’t aim to provide all features for all users.

1.1. License

Distributed under the highly permissive Boost Software License, Version 1.0. (See accompanying file LICENSE.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

1.2. 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.

2. Usage

To use, just #include <lyra/lyra.hpp>

2.1. Single Option

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

#include <cstdlib>
#include <iostream>
#include <lyra/lyra.hpp>

int main(int argc, const char** argv)
{
    // Where we read in the argument value:
    int width = 0;

    // The parser with the one option argument:
    auto cli = lyra::cli()
        | lyra::opt(width, "width")
              ["-w"]["--width"]("How wide should it be?");

    // ...

You can use this parser by giving it the program arguments of main:

    // ...

    // Parse the program arguments:
    auto result = cli.parse({ argc, argv });

    // Check that the arguments where valid:
    if (!result)
    {
        std::cerr << "Error in command line: " << result.errorMessage() << std::endl;
        return 1;
    }

    std::cout << "width = " << width << "\n";
    return 0;
}

Which could be used as:

> example1 -w 10
width = 10

2.2. Multiple Options

It’s rare that we are interested in accepting a single option. To parse multiple options we compose the options as alternatives with the or operator (|).

#include <cstdlib>
#include <iostream>
#include <lyra/lyra.hpp>

int main(int argc, const char** argv)
{
    // Where we read in the argument values:
    int width = 0;
    std::string name;
    bool doIt = false;

    // The parser with the multiple option arguments. They are composed
    // together by the "|" operator.
    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");

    // ...

You can use this parser by giving it the program arguments of main:

    // ...

    // Parse the program arguments:
    auto result = cli.parse({ argc, argv });

    // Check that the arguments where valid:
    if (!result)
    {
        std::cerr << "Error in command line: " << result.errorMessage() << std::endl;
        return 1;
    }

    std::cout << "width = " << width << ", name = " << name << ", doIt = " << doIt << "\n";
    return 0;
}

Which could be used as:

> example2 -w 10 --name=Lyra
width = 10, name = Lyra, doIt = 0

3. Alternate Specification

Using operators for specifying the parser argument is not everyone’s "cup of tea". Like all such interface choices there are advantages and disadvantages to any particular API one chooses. Because of this Lyra supports both the preceding operator model and a "named arguments using methods" model for specifying the arguments. Below are the various specification operations and corresponding operator and method call equivalents:

Help description

parser("Help")

parser.help("Help")

Optional argument

parser.optional()

parser.optional()

Required argument

parser.required()

parser.required()

Range of arguments

parser.cardinality(n,m)

parser.cardinality(n,m)

Value choices

parser.choices(a,b,c)

parser.choices(a,b,c)

Add argument

parser |= argument

parser.add_argument(argument)

Add option name

option["--name"]

option.name("--name")

Help option description

help.description("Description")

help.description("Description")

The method names try to follow the well known Python argparse nomenclature for familiarity. Using the alternative methods one could rewrite the previous two examples. The first one with the single option would be:

#include <cstdlib>
#include <iostream>
#include <lyra/lyra.hpp>

int main(int argc, const char** argv)
{
    // Where we read in the argument value:
    int width = 0;

    // The parser with the one option argument:
    auto cli = lyra::cli();
    cli.add_argument(
        lyra::opt(width, "width")
            .name("-w")
            .name("--width")
            .help("How wide should it be?"));

    // Parse the program arguments:
    auto result = cli.parse({ argc, argv });

    // Check that the arguments where valid:
    if (!result)
    {
        std::cerr << "Error in command line: " << result.errorMessage() << std::endl;
        return 1;
    }

    std::cout << "width = " << width << "\n";
    return 0;
}

And the second with multiple options would the become:

#include <cstdlib>
#include <iostream>
#include <lyra/lyra.hpp>

int main(int argc, const char** argv)
{
    // Where we read in the argument values:
    int width = 0;
    std::string name;
    bool doIt = false;

    // The parser with the multiple option arguments. They are composed
    // together by the "|" operator.
    auto cli = lyra::cli();
    cli.add_argument(lyra::opt(width, "width")
        .name("-w").name("--width").help("How wide should it be?"));
    cli.add_argument(lyra::opt(name, "name")
        .name("-n").name("--name").help("By what name should I be known"));
    cli.add_argument(lyra::opt(doIt)
        .name("-d").name("--doit").help("Do the thing"));

    // Parse the program arguments:
    auto result = cli.parse({ argc, argv });

    // Check that the arguments where valid:
    if (!result)
    {
        std::cerr << "Error in command line: " << result.errorMessage() << std::endl;
        return 1;
    }

    std::cout << "width = " << width << ", name = " << name << ", doIt = " << doIt << "\n";
    return 0;
}

4. Help Option

From the specified arguments parser we also get convenient help output.

int main(int argc, const char** argv)
{
    // Where we read in the argument values:
    int width = 0;
    std::string name;
    bool doIt = false;
    bool show_help = false; (1)

    // The parser with the multiple option arguments and help option.
    auto cli
        = lyra::help(show_help) (2)
        | 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");

    // ...
1 Flag variable to indicate if we get the -h or --help option.
2 The help specific option parser.

We need some changes when using the parser to check if the help option was specified:

    // ...

    // Parse the program arguments:
    auto result = cli.parse({ argc, argv });

    // Check that the arguments where valid:
    if (!result)
    {
        std::cerr << "Error in command line: " << result.errorMessage() << std::endl;
        std::cerr << cli << "\n"; (1)
        return 1;
    }

    // Show the help when asked for.
    if (show_help) (2)
    {
        std::cout << cli << "\n";
        return 0;
    }

    std::cout << "width = " << width << ", name = " << name << ", doIt = " << doIt << "\n";
    return 0;
}
1 We print out the help text on error.
2 And we also print it out when specified.

5. Value Choices

For value arguments, i.e. --name=value or positional arguments, one can specify a set of allowed values. You can indicate the choices explicitly by specifying them to the choices() call:

#include <iostream>
#include <lyra/lyra.hpp>

int main(int argc, const char** argv)
{
    std::string choice;
    // Ex: <exe> --choice=red
    auto cli = lyra::cli()
        | lyra::opt(choice, "-c")["--choice"]
              .choices("red", "green", "blue");
    auto result = cli.parse({ argc, argv });
    if (result)
    {
        std::cout << "Your preferred color is " << choice << "\n";
        return 0;
    }
    else
    {
        std::cerr << result.errorMessage() << "\n";
        return 1;
    }
}

Or you can specify a complex set of values by giving choices() a function that validates if a given value is allowed:

#include <iostream>
#include <lyra/lyra.hpp>

int main(int argc, const char** argv)
{
    int choice = 5;
    // Ex: <exe> --choice=3
    auto cli = lyra::cli()
        | lyra::opt(choice, "-c")["--choice"]
              .choices([](int value) { return 1 <= value && value <= 10; });
    auto result = cli.parse({ argc, argv });
    if (result)
    {
        std::cout << "Your number between one and ten is " << choice << "\n";
        return 0;
    }
    else
    {
        std::cerr << result.errorMessage() << "\n";
        return 1;
    }
}

For either case the default, initial, value is only modified if a valid value is given.

6. Option Values

For options that are bound to values, and hence that accept a user value on the command line, various styles of option+value syntax is allowed for the user as follows:

Long options

opt(v, "value").name("--option")

--option VALUE, --option=VALUE

Short options

opt(v, "value").name("-o")

-o VALUE, --o=VALUE, -oVALUE

7. Sub-commands

A common program pattern is to have a single "shell" program that performs various independent commands. For example you have git commit.., git push.., and so on. It’s possible to create such sub-command parsers in Lyra with the use of arguments, group and literal parsers manually. But as this is a very common use case the library provides a convenience group parser for the occasion.

In this example we use two command parameters to specify the sub-commands and a lambda to execute the subcommands.

#include <lyra/lyra.hpp>

#include <iostream>
#include <string>
#include <vector>

// Run a process, sub-command data.
struct run_command (1)
{
    std::vector<std::string> command; (2)
    bool verbose = false;
    bool show_help = false;

    run_command(lyra::cli & cli) (3)
    {
        cli.add_argument(
            lyra::command("run",
                [this](const lyra::group & g) { this->do_command(g); }) (4)
                .help("Execute the given command.")
                .add_argument(lyra::help(show_help))
                .add_argument(
                    lyra::opt(verbose)
                        .name("-v")
                        .name("--verbose")
                        .optional()
                        .help(
                            "Show additional output as to what we are doing."))
                .add_argument(
                    lyra::arg(command, "command")
                        .required()
                        .help(
                            "The command, and arguments, to attempt to run.")));
    }

    void do_command(const lyra::group & g)
    {
        if (show_help)
            std::cout << g; (5)
        else
        {
            std::cout << "RUN: "
                      << "verbose=" << (verbose ? "true" : "false");
            for (auto c : command) std::cout << " " << c;
            std::cout << "\n";
        }
    }
};

// Kill a named process, sub-command data.
struct kill_command (6)
{
    std::string process_name;
    int signal = 9;
    bool show_help = false;

    kill_command(lyra::cli & cli)
    {
        cli.add_argument(
            lyra::command(
                "kill", [this](const lyra::group & g) { this->do_command(g); })
                .help("Terminate the process with the given name.")
                .add_argument(lyra::help(show_help))
                .add_argument(
                    lyra::opt(signal, "signal")
                        .name("-s")
                        .name("--signal")
                        .optional()
                        .help(
                            "The signal integer to post to the running process."))
                .add_argument(
                    lyra::arg(process_name, "process_name")
                        .required()
                        .help(
                            "The name of the process to search and signal.")));
    }

    void do_command(const lyra::group & g)
    {
        if (show_help)
            std::cout << g;
        else
            std::cout << "KILL:"
                      << " signal=" << signal << " process=" << process_name
                      << "\n";
    }
};

int main(int argc, const char ** argv)
{
    auto cli = lyra::cli();
    std::string command;
    bool show_help = false;
    cli.add_argument(lyra::help(show_help));
    kill_command kill { cli };
    run_command run { cli };
    auto result = cli.parse({ argc, argv }); (7)
    if (show_help)
    {
        std::cout << cli;
        return 0;
    }
    if (!result) (8)
    {
        std::cerr << result.errorMessage() << "\n";
    }
    return result ? 0 : 1;
}
1 A simple struct for information on the sub-commands. First for our run sub-command.
2 The arguments for the sub-command.
3 The constructor defines the additional arguments for the sub-command in the given cli.
4 Each sub-command sets a callback for when the group is successfully parsed which tells us we have a valid command to respond to.
5 We specified a sub-command specific help option. Here we can check for it and print out the help for the group only. This help will look similar to the full help output, but only contains the group arguments.
6 And now the information for our kill sub-comand.
7 We go ahead and parse the top-level cli which will also parse the sub-command groups.
8 At the end we can do the regular error handling.

8. Argument Groups

There are times when some CLI arguments only make sense when considered as a collection. A common case for this are commands. But it also comes up in any case where some arguments are all required, but only if one of them is present. Lets take the example of specifying the dimension of a window. For example one could expect both --width=X and --height=Y options. But you could make them optional, as a group, in favor of an automatic screen sized window of a particular aspect ratio with a --aspect=R option. In such a case we would want to allow either one of these to be specified:

exec --width=1440 --height=720
exec --aspect=1.78

With argument groups we can allow such an arrangement.

#include <lyra/lyra.hpp>

#include <iostream>
#include <string>
#include <vector>

int main(int argc, const char ** argv)
{
    // Default to showing a full screen 4/3 aspect
    bool show_full_screen = true;
    float aspect = 4.0f / 3.0f;

    // If it's not full screen the size will be specified.
    unsigned width = 0;
    unsigned height = 0;

    // Did the user ask for help?
    bool get_help = false;

    lyra::cli cli;
    cli.add_argument(lyra::help(get_help))
        .add_argument(lyra::opt(aspect, "aspect") (1)
                          .name("--aspect")
                          .help("Full-screen aspect ratio window."))
        .add_argument(lyra::group([&](const lyra::group &) {
                          show_full_screen = false;
                      }) (2)
                          .add_argument(lyra::opt(width, "width") (3)
                                            .required()
                                            .name("--width")
                                            .help("Width of window."))
                          .add_argument(lyra::opt(height, "height")
                                            .required() (4)
                                            .name("--height")
                                            .help("Height of window.")));

    // Parse the program arguments.
    auto result = cli.parse({ argc, argv });

    if (get_help)
    {
        std::cout << cli;
        return 0;
    }

    // Check that the arguments where valid.
    if (!result)
    {
        std::cerr << "Error in command line: " << result.errorMessage()
                  << std::endl;
        return 1;
    }

    if (show_full_screen)
    {
        std::cout << "Full screen aspect = " << aspect << "\n";
    }
    else
    {
        std::cout << "Window size = " << width << " x " << height << "\n";
    }

    return 0;
}
1 The ratio option is a regular value argument.
2 The group for the window size turns off the full screen mode when the size options are fully specified.
3 We add the width and height options to the group.
4 We specify both the width and height as required to ensure we get only a valid specification when both are present. Otherwise the group is ignored as optional.

9. Main

For many cases specifying a help option, handling it, and specifying additional arguments introduces boilerplate that can get in the way of managing "easy" command lines. The lyra::main class abstract most of that boilerplate to make it trivial to create and handle a command line.

In this example we define and use two options and one positional argument. It then executes the lambda with the parsed command line as given by argv.

#include <iostream>
#include <lyra/lyra.hpp>

int main(int argc, const char ** argv)
{
    return lyra::main() (1)
        ("-x", 0)("-y", 0)("z", 5) (2)
        (argc, argv, [](lyra::main & m) { (3)
            std::cout << (int(m["-x"]) + int(m["-y"])) * int(m["z"]) << "\n"; (4)
            return 0; (5)
        });
}
1 Use the lyra::main utility by creating an instance of it.
2 Define two options and one positional argument. Each one defines the one option, or hint, and the default value (and type of value).
3 Define and execute the body of the program passed in as a lambda.
4 Access the individual options and argument from any of their names or hint. Each is converted to the specified type (int in this case).
5 Return an appropriate value that is also return from main entry function.

10. More Main

Using the simple lyra::main interface can’t possibly cover the variety of use cases people want. In particular when it comes to the options and arguments. For that teh lyra::main interface supports adding instances of the regular option and argument parsers.

In this example we define and use two options and one positional argument, as before. But we use lyra::opt and lyra::arg specifications. We also use the lyra::val value holder to provide the location for the parsed value and it’s parsed type.

#include <iostream>
#include <lyra/lyra.hpp>

int main(int argc, const char ** argv)
{
    return lyra::main()
        (lyra::opt(lyra::val(0), "x")["-x"]) (1)
        (lyra::opt(lyra::val(0), "y")["-y"])
        (lyra::arg(lyra::val(5), "z")) (2)
        (argc, argv, [](lyra::main & m)
        {
            std::cout << (int(m["-x"]) + int(m["-y"]))*int(m["z"]) << "\n";
            return 0;
        });
}
1 Add the "-x" option as an integer with a default of 0.
2 The positional argument in this case has a default of 5.

11. Reference

11.1. lyra::parser_customization

Customization interface for parsing of options.

virtual std::string token_delimiters() const = 0;

Specifies the characters to use for splitting a cli argument into the option and its value (if any).

virtual std::string option_prefix() const = 0;

Specifies the characters to use as possible prefix, either single or double, for all options.

11.2. lyra::default_parser_customization

Is-a lyra::parser_customization that defines token delimiters as space (" ") or equal (=). And specifies the option prefix character as dash (-) resulting in long options with -- and short options with -.

This customization is used as the default if none is given.

11.3. lyra::parser_result

The result of parsing arguments.

11.4. lyra::parser

Base for all argument parser types.

11.4.1. Specification

11.4.1.1. lyra::parser::help_text_item
struct lyra::parser::help_text_item
{
    std::string option;
    std::string description;
};

Holds the help information for a single argument option. The option member is the long name of the option. And the description is the text describing the option. A list of them is returned from the lyra::parser::get_help_text method.

11.4.1.2. lyra::parser::help_text
using help_text = std::vector<help_text_item>;

The set of help texts for any options in the sub-parsers to this one, if any.

11.4.1.3. lyra::parser::get_help_text
virtual help_text get_help_text() const;

Collects, and returns, the set of help items for the sub-parser arguments in this parser, if any. The default is to return an empty set. Which is what most parsers will return. Parsers like arguments, group, and cli will return a set for the arguments defined. This is called to print out the help text from the stream operator.

11.4.1.4. lyra::parser::get_usage_text
virtual std::string get_usage_text() const;

Returns the formatted USAGE text for this parser, and any contained sub-parsers. This is called to print out the help text from the stream operator.

11.4.1.5. lyra::parser::get_description_text
virtual std::string get_description_text() const;

Returns the description text for this, and any contained sub-parsers. This is called to print out the help text from the stream operator.

11.5. lyra::composable_parser

A parser that can be composed with other parsers using operator|. Composing two composable_parser instances generates a cli parser.

11.6. lyra::bound_parser

Parser that binds a variable reference or callback to the value of an argument.

11.6.1. Construction

template <typename Derived>
template <typename Reference>
bound_parser<Derived>::bound_parser(Reference& ref, std::string const& hint);

template <typename Derived>
template <typename Lambda>
bound_parser<Derived>::bound_parser(Lambda const& ref, std::string const& hint);

Constructs a value option with a target typed variable or callback. These are options that take a value as in --opt=value. In the first form the given ref receives the value of the option after parsing. The second form the callback is called during the parse with the given value. Both take a hint that is used in the help text. When the option can be specified multiple times the callback will be called consecutively for each option value given. And if a container is given as a reference on the first form it will contain all the specified values.

11.6.2. Specification

11.6.2.1. lyra::bound_parser::help, lyra::bound_parser::operator(help)
template <typename Derived>
Derived& bound_parser<Derived>::help(std::string const& text);
template <typename Derived>
Derived& bound_parser<Derived>::operator()(std::string const& help);

Defines the help description of an argument.

11.6.2.2. lyra::bound_parser::optional
template <typename Derived>
Derived& bound_parser<Derived>::optional();

Indicates that the argument is optional. This is equivalent to specifying cardinality(0, 1).

11.6.2.3. lyra::bound_parser::required(n)
template <typename Derived>
Derived& bound_parser<Derived>::required(size_t n);

Specifies that the argument needs to given the number of n times (defaults to 1).

11.6.2.4. lyra::bound_parser::cardinality(n, m)
template <typename Derived>
Derived& bound_parser<Derived>::cardinality(size_t n);

template <typename Derived>
Derived& bound_parser<Derived>::cardinality(size_t n, size_t m);

Specifies the number of times the argument can and needs to appear in the list of arguments. In the first form the argument can appear exactly n times. In the second form it specifies that the argument can appear from n to m times inclusive.

11.6.2.5. lyra::bound_parser::choices
template <typename Derived>
template <typename T, typename... Rest>
lyra::opt& lyra::bound_parser<Derived>::choices(T val0, Rest... rest)

template <typename Derived>
template <typename Lambda>
lyra::opt& lyra::bound_parser<Derived>::choices(Lambda const &check_choice)

Limit the allowed values of an argument. In the first form the value is limited to the ones listed in the call (two or more values). In the second form the check_choice function is called with the parsed value and returns true if it’s an allowed value.

11.7. lyra::cli

A Combined parser made up of any two or more other parsers. Creating and using one of these as a basis one can incrementally compose other parsers into this one. For example:

auto cli = lyra::cli();
std::string what;
float when = 0;
std::string where;
cli |= lyra::opt(what, "what")["--make-it-so"]("Make it so.").required();
cli |= lyra::opt(when. "when")["--time"]("When to do <what>.").optional();
cli.add_argument(lyra::opt(where, "where").name("--where")
    .help("There you are.").optional());

11.7.1. Construction

11.7.1.1. Default
cli() = default;

Default constructing a cli is the starting point to adding arguments and options for parsing a command line.

11.7.1.2. Copy
cli::cli(const cli& other);

11.7.2. Specification

11.7.2.1. lyra::cli::add_argument
cli& cli::add_argument(exe_name const& exe_name);
cli& cli::operator|=(exe_name const& exe_name);
cli& cli::add_argument(parser const& p);
cli& cli::operator|=(parser const& p);
cli& cli::add_argument(group const& p);
cli& cli::operator|=(group const& p);
cli& cli::add_argument(cli const& other);
cli& cli::operator|=(cli const& other);

Adds the given argument parser to the considered arguments for this cli. Depending on the parser given it will be: recorded as the exe name (for exe_name parser), directly added as an argument (for parser), or add the parsers from another cli to this one.

11.7.2.2. lyra::cli::operator[]
cli::value_result cli::operator[](const std::string & n)

Finds the given argument by either option name or hint name and returns a convertible reference to the value, either the one provided by the user or the default.

11.7.2.3. lyra::cli::parse
parse_result cli::parse(
    args const& args, parser_customization const& customize) const;

Parses given arguments args and optional parser customization customize. The result indicates success or failure, and if failure what kind of failure it was. The state of variables bound to options is unspecified and any bound callbacks may have been called.

11.8. lyra::opt

A parser for one option with multiple possible names. The option value(s) are communicated through a reference to a variable, a container, or a callback.

11.8.1. Construction

11.8.1.1. Flags
lyra::opt::opt(bool& ref);

template <typename L>
lyra::opt::opt(L const& ref);

Constructs a flag option with a target bool to indicate if the flag is present. The first form takes a reference to a variable to receive the bool. The second takes a callback that is called with true when the option is present.

11.8.1.2. Values
template <typename T>
lyra::opt::opt(T& ref, std::string const& hint);

template <typename L>
lyra::opt::opt(L const& ref, std::string const& hint)

Constructs a value option with a target ref. The first form takes a reference to a variable to receive the value. The second takes a callback that is called with the value when the option is present.

11.8.2. Specification

11.8.2.1. lyra::opt::name
lyra::opt& lyra::opt::name(const std::string &opt_name)
lyra::opt& lyra::opt::operator[](const std::string &optName)

Add a spelling for the option of the form --<name> or -n. One can add multiple short spellings at once with -abc.

11.9. lyra::arg

A parser for regular arguments, i.e. not -- or - prefixed. This is simply a way to get values of arguments directly specified in the cli.

11.10. lyra::help

Utility function that defines a default --help option. You can specify a bool flag to indicate if the help option was specified and that you could display a help message.

The option accepts -?, -h, and --help as allowed option names.

help & help::description(const std::string &text)

Sets the given text as the general description to show with the help and usage output for CLI parser. This text is displayed between the "Usage" and "Options, arguments" sections.

11.11. lyra::exe_name

Specifies the name of the executable.

11.11.1. Construction

exe_name::exe_name(std::string& ref)

Constructs with a target string to receive the name of the executable. When the cli is run the target string will contain the exec name.

template <typename LambdaT>
exe_name::exe_name(LambdaT const& lambda)

Construct with a callback that is called with the value of the executable name when the cli runs.

11.11.2. Accessors

11.11.2.1. lyra::exe_name::name
std::string exe_name::name() const

Returns the executable name when available. Otherwise it returns a default value.

11.11.2.2. lyra::exe_name::set
parser_result exe_name::set(std::string const& newName)

Sets the executable name with the newName value. The new value is reflected in the bound string reference or callback.

11.12. lyra::args

Transport for raw args (copied from main args, supplied via init list, or from a pair of iterators).

11.13. lyra::arguments

A Combined parser made up of any number of parsers. Creating and using one of these as a basis one can incrementally compose other parsers into this one. For example:

auto p = lyra::arguments();
std::string what;
float when = 0;
std::string where;
p |= lyra::opt(what, "what")["--make-it-so"]("Make it so.").required();
p |= lyra::opt(when. "when")["--time"]("When to do <what>.").optional();
p.add_argument(lyra::opt(where, "where").name("--where")
    .help("There you are.").optional());

11.13.1. Construction

11.13.1.1. Default
arguments() = default;

Default constructing a arguments is the starting point to adding arguments and options for parsing a arguments line.

11.13.1.2. Copy
arguments::arguments(const arguments& other);

11.13.2. Specification

11.13.2.1. lyra::arguments::add_argument
arguments& arguments::add_argument(parser const& p);
arguments& arguments::operator|=(parser const& p);
arguments& arguments::add_argument(arguments const& other);
arguments& arguments::operator|=(arguments const& other);

Adds the given argument parser to the considered arguments for this arguments. Depending on the parser given it will be: directly added as an argument (for parser), or add the parsers from another arguments to this one.

11.13.2.2. lyra::arguments::sequential
arguments & arguments::sequential();

Sets the parsing mode for the arguments to "sequential". When parsing the arguments they will be, greedily, consumed in the order they where added. This is useful for sub-commands and structured command lines.

11.13.2.3. lyra::arguments::inclusive
arguments & arguments::inclusive();

Sets the parsing mode for the arguments to "inclusively any". This is the default that attempts to match each parsed argument with all the available parsers. This means that there is no ordering enforced.

11.13.2.4. lyra::arguments::get
template <typename T>
T & arguments::get(size_t i);

Get a modifyable reference to one of the parsers specified.

11.14. lyra::literal

A parser that matches a single fixed value.

Is-a lyra::parser.

11.14.1. Construction

11.14.1.1. Token
inline literal::literal(std::string const& n)

Constructs the literal with the name of the token to match.

11.14.2. Specification

11.14.2.1. lyra:literal::help
literal& literal::help(const std::string& text)
literal& literal::operator()(std::string const& description)

Specify a help description for the literal.

11.15. lyra::group

A group of arguments provides for parsing, optionally, a set of arguments together. The group itself is considered successfully parsed only when the arguments in the group are parsed without errors. A common use case for this are sub-commands. This implementation is recursive. And hence allows groups within groups for describing branching argument parsing.

11.15.1. Construction

11.15.1.1. Default
group() = default;

Default constructing a group does not register the success callback.

11.15.1.2. Copy
group::group(const group& other);
11.15.1.3. Success Handler
group::group(const std::function<void(const group &)> & f)

Registers a function to call when the group is successfully parsed. The function is called with the group to facilitate customization.

11.16. lyra::command

A parser that encapsulates the pattern of parsing sub-commands. It provides a quick wrapper for the equivalent arrangement of group and literal parsers. For example:

lyra::command c = lyra::command("sub");

Is equivalent to:

lyra::command c = lyra::group()
    .sequential()
    .add_argument(literal("sub"))
    .add_argument(group());
lyra::group & g = c.get<lyra::group>(1);

I.e. it’s conposed of a literal followed by the rest of the command arguments.

Is-a lyra::group.

11.16.1. Construction

command::command(const std::string & n);
command::command(
    const std::string & n, const std::function<void(const group &)>& f);

To construct an command we need a name (n) that matches, and triggers, that command.

11.16.2. Specification

11.16.2.1. lyra:command::help
command & command::help(const std::string& text)
command & command::operator()(std::string const& description)

Specify a help description for the command. This sets the help for the underlying literal of the command.

11.16.2.2. lyra::command::add_argument
template <typename P>
command & command::add_argument(P const & p);
template <typename P>
command & command::operator|=(parser const & p);

Adds the given argument parser to the considered arguments for this comand. The argument is added to the sub-group argument instead of this one. Hence it has the effect of adding arguments after the command name.

11.17. lyra::main

Encapsulates the common use case of a main program that has a help option and has a minimal way to specify and parse options. This provides for a way to specify options and arguments in a simple function form. It handles checking for errors and reporting problems.

11.17.1. Construction

main::main(const std::string & text);

Construct with text for description, which defaults to an empty string. The description is specified for the help option that is added to the command line.

11.17.2. Add Argument

template <typename T> main & main::operator()(const T & parser)
template <typename T> main & main::add_argument(const T & parser)
template <typename T> main & main::operator|=(const T & parser)

Adds a parser as an argument to the command line. These forward directly to the lyra::cli equivalents. The added parser can be any of the regular Lyra parsers like lyra::opt or lyra::arg.

11.17.3. Simple Args

template <typename V>
main & main::operator()(
    std::initializer_list<std::string> arg_names, V && default_value)
template <typename V>
main & main::operator()(const std::string & arg_name, V && default_value)

Specifies, and adds, a new argument. Depending on the arg_names it can be either a lyra::opt or lyra::arg. The first item in arg_names indicates the type of argument created and added:

Specify either -<name> or --<name> to add a lyra::opt. You can specify as many option names following the first name. A name that doesn’t follow the option syntax is considered the as the help text for the option.

Specify a non - prefixed name as the first item to signify a positional lyra::arg.

The single std::string call is equivalent to specifying just the one option or argument.

Example specifications:

("-o", 0)

Short -o option as int value.

("--opt", 0)

Long --opt option as int value.

({"-o", "--opt"}, 1.0f)

Short and long option as float value.

({"-o", "The option."}, 1.0f)

Short option and help description as float value.

("opt", 2)

Positional, i.e. lyra::arg, argument as int value.

({"opt", "The option."}, 2)

Positional argument and help description as int value.

("--opt", std::vector<float>())

Long option with as multiple float values.

11.17.4. Execute

template <typename L>
int main::operator()(const args & argv, L action)
template <typename L>
int main::operator()(int argc, const char ** argv, L action)

Executes the given action after parsing of the program input arguments. It returns either 0 or 1 if the execution was successful or failed respectively. The action is called with the lyra::main instance to provide access to the parsed argument values.

11.18. lyra::val

auto val(T && v);
auto val(const char * v);

Makes a bound self-contained value of the type of the given r-value. The created bound values can be used in place of the value references for arguments. And can be retrieved with the lyra::cli::operator[] call.

12. History

12.1. 1.5.1

Minor change to bring back the missing option argument hints from the usage help output.

12.2. 1.5

This release has some big changes in easy of use and functionality. There are now alternate interfaces for specifying and fetching arguments. Also the help output is now more compact and clearer. There is also new support for sub-commands.

The cli_parser type was renamed to cli. Both the cli_parser type and the lyra/cli_parser.hpp header are deprecated and will be removed in a future release.
Changed the install CMake target from BFG::Lyra to bfg::lyra.

Changes:

  • New: Main encapsulation of common use case of help option handling. With shorthand specification of arguments. — René Ferdinand Rivera Morell

  • New: Ability to specify argument values, with default, without specifying a local external to the parser variable. Making it easier to specify command lines. The values can be retrieved from the cli as a map from argument names to the value. — René Ferdinand Rivera Morell

  • New: Support construction of lyra::args from iterators for cases where the arguments come from some existing container. — René Ferdinand Rivera Morell

  • New: Add Cmake install support. — Jayesh Vinay Badwaik

  • New: Command argument to make it easy to specify sub-commands. — René Ferdinand Rivera Morell

  • New: Alternative sequential argument parsing mode. — René Ferdinand Rivera Morell

  • New: Grouped arguments to specify and handle sub-command parsers. — René Ferdinand Rivera Morell

  • New: literal parser to directly match an argument. — René Ferdinand Rivera Morell

  • Fix missing hint text for optional, lyra::arg, arguments. — René Ferdinand Rivera Morell

  • Bring back some cleaner and compact formatting of the help text. — René Ferdinand Rivera Morell

  • Tested with Visual Studio 2017, VS 2019, MinGW-64 (gcc 8.1.0), Linux ( clang 3.9, 4, 5, 6, 7, 8, 9, 10; gcc 4.9, 5, 6, 7, 8, 9, 10), Xcode ( 11.1, 11.2.1, 11.3.1, 11.4.1, 11.5, 11.6), on Azure Pipelines; and with VS 2015, MinGW-64 (gcc 6.3, 7.3) on AppVeyor.

12.3. 1.4

Changes:

  • New: Allow passing option value choices as an array. — René Ferdinand Rivera Morell

  • Fix sample code in README to be correctly namespaced. — Jayesh Badwaik

  • Fix commands example to actually show help when specified. — Shreyas Potnis

  • Tested with Visual Studio 2017, VS 2019, MinGW-64 (gcc 8.1.0), Linux ( clang 3.8, 3.9, 4, 5, 6, 7, 8, 9, 10; gcc 4.8, 4.9, 5, 6, 7, 8, 9, 10), Xcode ( 10.1, 10.2.1, 10.3, 11.1, 11.2.1, 11.3.1, 11.4), on Azure Pipelines; and with VS 2015, MinGW-64 (gcc 6.3, 7.3) on AppVeyor.

12.4. 1.3

Changes:

  • New: Accept -o2 style option+value arguments. — René Ferdinand Rivera Morell

  • New: Accept -abc option name spelling as shorthand for -a, -b, -c. — René Ferdinand Rivera Morell

  • Fixed inconsistent handling of option values that look like options, like negative numbers. — René Ferdinand Rivera Morell

  • Rewrote argument token parsing for clarity, to avoid extra token buffer allocation, and to allow for more option & value variations. — René Ferdinand Rivera Morell

  • Fixed allowing junk extra characters after a non-string option value. — René Ferdinand Rivera Morell

  • Support specifying a single value for choices of an argument. — René Ferdinand Rivera Morell

  • Fix various problems with the commands example program. Also now the examples for the documentation are unit tested along with the regular unit tests. — René Ferdinand Rivera Morell

  • Tested with Visual Studio 2015, VS 2017, VS 2019, MinGW-64 (gcc 8.1), Linux (clang 3.5, 3.6, 3.7, 3.8, 3.9, 4, 5, 6, 7, 8, 9; gcc 4.8, 4.9, 5, 6, 7, 8, 9), Xcode (9.0, 9.0.1, 9.1, 9.2, 9.3, 9.3.1, 9.4, 9.4.1, 10.0, 10.1, 10.2, 10.2.1, 10.3, 11.0, 11.1, 11.2, 11.2.1), on Azure Pipelines.

12.5. 1.2

Changes:

  • New: One can now accept 1-or-more on bound container arguments by only specifying required() on such arguments. — René Ferdinand Rivera Morell

  • New: One can now define a description text to display as general command information with the help::description method. — René Ferdinand Rivera Morell

  • New: Add named methods as alternates for operators to add and specify arguments. They follow the familiar Python argparse nomenclature. — René Ferdinand Rivera Morell

  • New: Single header file alternative version of the library. For those that need or want such a thing. — René Ferdinand Rivera Morell

  • Improve help for arguments that specify a cardinality. — René Ferdinand Rivera Morell

  • Addition of more complicated use cases to demonstrate flexibility of library. — René Ferdinand Rivera Morell

  • Continued internal clean up of code for stability and easier future enhancements. — René Ferdinand Rivera Morell

  • Tested with Visual Studio 2015, VS 2017, VS 2019, MinGW-64 (gcc 8.1), Linux (clang 3.5, 3.6, 3.7, 3.8, 3.9, 4, 5, 6, 7, 8, 9; gcc 4.8, 4.9, 5, 6, 7, 8, 9), Xcode (9.0, 9.0.1, 9.1, 9.2, 9.3, 9.3.1, 9.4, 9.4.1, 10.0, 10.1, 10.2, 10.2.1, 10.3, 11.0, 11.1, 11.2, 11.2.1), on Azure Pipelines.

12.6. 1.1

Changes:

  • New: Add direct Meson Build use support. — Rémi Gastaldi

  • New: Define argument value choices() as either a fixed set or checked by a custom lambda function. — René Ferdinand Rivera Morell

  • Fix being able to parse straight from args outside of cli. Which resulted in misleading parsing behavior. René Ferdinand Rivera Morell

  • Fix use of cardinality() to correctly constrain bounded cardinality ranges like [0,n], [n,m], [n,n], and [0,0] (unbounded). René Ferdinand Rivera Morell

  • Fix use of required() arguments such that the parse errors if they are absent. — girstsf

  • Remove uses of assert macro to avoid internal aborts and make it easier to use as a library. — René Ferdinand Rivera Morell

  • Many documentation improvements. — René Ferdinand Rivera Morell

  • Tested with Visual Studio 2015, VS 2017, VS 2019, MinGW-64 (gcc 8.1), Linux (clang 3.5, 3.6, 3.7, 3.8, 3.9, 4, 5, 6, 7, 8, 9; gcc 4.8, 4.9, 5, 6, 7, 8, 9), Xcode (9.0, 9.0.1, 9.1, 9.2, 9.3, 9.3.1, 9.4, 9.4.1, 10.0, 10.1, 10.2, 10.2.1, 10.3, 11.0), on Azure Pipelines.

12.7. 1.0

This is the initial base version based on Clara library. Changes from that library:

  • Documentation.

  • Zero dependencies, even internally, by removing TextFlow and Catch bundled libraries.

  • Conform to Pitchfork Layout R1.

  • Tested with Visual Studio 2015, VS 2017, MinGW (gcc 5.3), MinGW-64 (gcc 6.3, 7.3, 8.1), Linux (clang 3.5, 3.8, 3.9, 4, 5; gcc 4.8, 4.9, 5, 6, 7, 8), Xcode (8.3, 9, 9.1, 10.1).

  • Tested with C++ 11, 14, 17, and 2a.

  • New: customization of option prefix and separators.

  • New: support for repeated arguments, from one to many.