Clara: A Powerful Command Line Parsing Library for C++

Clara: A Powerful Command Line Parsing Library for C++

Clara is a simple, composable command line parsing library suitable for C++11 and later. It is a single-header library with no external dependencies (other than the standard library), making it very lightweight and easy to integrate into projects.

Easy to Use

The design goal of Clara is to make command line argument parsing simple and intuitive. You only need to include a single header file clara.hpp to get started. For example, creating a parser to parse an option is very straightforward:

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

This code defines an option named width, which can be specified using -w or --width.

Composability

Another powerful feature of Clara is its composability. Each Opt or Arg is an independent parser that can be combined using the | operator to form a composite parser. This composition can be done incrementally across multiple function calls, and even across different projects. For example:

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");

Variable Binding and Type Inference

Clara allows direct binding of parsers to variables, so the parsing results are stored directly in these variables without the need for an intermediate dictionary. Additionally, Clara can infer types from bound variables or lambda expressions and automatically handle type conversions and error handling in the background.

Error Handling

Clara uses result types to propagate errors instead of exceptions. This means you can handle errors by checking the return value without worrying about the complexities of exceptions.

POSIX Standard Support

Clara adheres to the POSIX standard, supporting the behavior of short and long options. This allows it to maintain consistent behavior with most command line tools on Unix-like systems.

Example Code

Here is a complete example code demonstrating how to use Clara to parse command line arguments:

#include <iostream>
#include <clara.hpp>

int main(int argc, char* argv[]) {
    int width = 0;
    std::string name;
    bool doIt = false;
    std::string command;

    using namespace clara;
    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");

    auto result = cli.parse(Args(argc, argv));
    if (!result) {
        std::cerr << "Error in command line: " << result.errorMessage() << std::endl;
        return 1;
    }

    std::cout << "Width: " << width << std::endl;
    std::cout << "Name: " << name << std::endl;
    std::cout << "Do it: " << doIt << std::endl;
    std::cout << "Command: " << command << std::endl;

    return 0;
}

Conclusion

Clara is a powerful and easy-to-use command line parsing library suitable for C++ projects. Its single-header design, composability, type inference, and error handling mechanisms make it an ideal choice for handling command line arguments. Whether for simple scripts or complex projects, Clara provides a clean and efficient solution.