Ookii.CommandLine.Cpp 2.0.1

Ookii.CommandLine for C++ is a powerful and flexible command line argument parsing library for C++ applications.

• Easily define strongly-typed arguments, with a simple builder API or using code-generation.
• Create applications with multiple subcommands.
• Generate fully customizable usage help.
• Supports PowerShell-like and POSIX-like parsing rules.
• Header-only library.

It requires a compiler that supports C++20.

Ookii.CommandLine can be used with any kind of C++ application, whether console or GUI. Some functions, such as creating usage help, are primarily designed for console applications, but even those can be easily adapted for use with other styles of applications.

Two styles of command line parsing rules are supported: the default mode uses rules similar to those used by PowerShell, and the alternative long/short mode uses a style influenced by POSIX conventions, where arguments have separate long and short names with different prefixes. Many aspects of the parsing rules are configurable.

To determine which arguments are accepted, first you create variables that will hold their values. Then, you use the ookii::parser_builder class to specify things such as the argument names, whether or not an argument is required, and descriptions used to customize the usage help, among other options. This creates an an ookii::command_line_parser, which can parse those arguments.

For example, the following code defines four arguments: a required positional argument, an optional positional argument, a named-only argument, and a switch argument (sometimes also called a flag):

std::string required_argument;
int optional_argument;
float named_argument;
bool switch_argument;

// argv[0] is used for the application executable name.
auto name = ookii::command_line_parser::get_executable_name(argc, argv);
auto parser = ookii::parser_builder{name}
    .add_argument(required_argument, "Required").required().positional()
        .description("A required positional argument.")
    .add_argument(optional_argument, "Optional").positional()
        .description("An optional positional argument.")
    .add_argument(named_argument, "Named")
        .description("An argument that can only supplied by name.")
    .add_argument(switch_argument, "Switch")
        .description("A switch argument, which doesn't require a value.")
    .build();

Each argument has a different type that determines the kinds of values it can accept.

To parse these arguments, all you have to do is call the following on the generated parser.

ookii::parse_result result = parser.parse(argc, argv, {});

This code will parse the arguments in the argv array, will handle and print errors to the console, and will print usage help if needed. It returns an ookii::parse_result that indicates if the operation was successful (it can be converted to bool for this purpose).

If the arguments are invalid, or help is requested, this application will print the following usage help:

Usage: sample_app [-Required] <string> [[-Optional] <int>] [-Help] [-Named <float>]
   [-Switch] [-Version]

    -Required <string>
        A required positional argument.

    -Optional <int>
        An optional positional argument.

    -Help [<bool>] (-?, -h)
        Displays this help message.

    -Named <float>
        An argument that can only supplied by name.

    -Switch [<bool>]
        A switch argument, which doesn't require a value.

The usage help includes the descriptions given for the arguments. The usage help format can also be fully customized.

The application also has one argument that wasn't explicitly defined, -Help, which is automatically added by default. You can also easily add a default -Version argument.

An example invocation of this application, specifying all the arguments, would look like this (argument names are case insensitive by default):

./MyApplication foo 42 -switch -named 5.6

Ookii.CommandLine also provides code generation scripts that can generate the above code using a specially annotated struct or class. For example, the below generates the same arguments as above:

// [arguments]
// [name_transform: PascalCase]
struct arguments
{
    // [argument, required, positional]
    // A required positional argument.
    std::string required;
    // [argument, positional]
    // An optional positional argument.
    int optional;
    // [argument]
    // An argument that can only supplied by name.
    float named;
    // [argument: Switch]
    // A switch argument, which doesn't require a value.
    bool switch_argument;

    OOKII_GENERATED_METHODS(arguments);
};

In addition, Ookii.CommandLine can be used to create applications that have multiple subcommands, each with their own arguments.

See the documentation on GitHub for more information, including a tutorial.