Ookii.CommandLine.Cpp 1.0.0

Ookii.CommandLine for C++ is a library that helps you to parse command line arguments for your applications. It allows you to easily define a set of accepted arguments, and then parse the command line supplied to your application for those arguments, converting the value of those arguments from a string to their specified type. In addition, it allows you to generate usage help from the arguments that you defined, which you can display to the user.

It requires a compiler that supports C++20.

Ookii.CommandLine can be used with any kind of C++ application, whether console or GUI. Although a limited subset of functionality—particularly related around generating usage help text—is geared primarily towards console applications that are invoked from the command line, the main command line parsing functionality is usable in any application that needs to process command line arguments.

To define a set of command line arguments, first you create variables that will hold their values. Then, you use the ookii::parser_builder class to construct an ookii::command_line_parser to parse those arguments, specifying things such as the argument names, whether or not an argument is required, and descriptions used to customize the usage help, among other options.

Command line parsing is done in a way that is similar to that used by PowerShell. Each argument has a name, and can be supplied by name on the command line. An argument can also be positional, in which case it can be supplied without the name. Arguments can be required or optional, and there is support for switch arguments (which don't need a value but are either present or not) and arguments with multiple values. Various aspects of the parsing, such as the argument name prefix (typically a - or a /), can be customized.

For example, the following code defines four arguments: a required positional argument, an optional positional argument, a named argument, and a switch argument:

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

// argv[0] is used for the application name.
auto parser = ookii::parser_builder{argv[0]}
    .add_argument(required_argument, "Required").required().positional()
    .add_argument(optional_argument, "Optional").positional()
    .add_argument(named_argument, "Named")
    .add_argument(switch_argument, "Switch")
    .build();

The application using these arguments would have the following usage syntax (this kind of usage help can be generated by Ookii.CommandLine, and can be customized to include argument descriptions):

Usage: MyApplication.exe [-Required] <string> [[-Optional] <int>] [-Named \<float>] [-Switch]

An example invocation of this application, specifying all the arguments, would look like this:

./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]
struct arguments
{
    // [argument, required, positional]
    std::string required;
    // [argument, positional]
    int optional;
    // [argument]
    float named;
    // [argument: Switch]
    bool switch_argument;

    OOKII_DECLARE_PARSE_METHOD(arguments);
};

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

For more information, see the documentation on GitHub.