Option parsing module

Provides a method of parsing command line arguments. More...

Modules
	Option Actions
	Actions provided by default.
	Option Parsing Errors
	Exceptions thrown by the optparse module.

Classes
struct	gears::optparse::formatter
	A class that handles the formatting of the help message. More...
struct	gears::optparse::option
	Represents a command line option. More...
struct	gears::optparse::option_parser
	Handles command line parsing. More...
struct	gears::optparse::option_set
	A container for holding options. More...
struct	gears::optparse::subcommand
	Represents a command line subcommand. More...
struct	gears::optparse::arguments
	Represents the parsed results of option_parser. More...
struct	gears::optparse::typed_value< T >
	Represents a command line value. More...

Detailed Description

This module is a way to parse command line arguments using conventional POSIX/Unix standards. It is a more convenient and flexible way of parsing command line options compared to rolling your own by hand. This module has built-in support for subcommands so you could make your own git-like programs with e.g. git commit and git add. This module is mainly inspired by Python's optparse library and Boost.ProgramOptions. A more in-depth tutorial can be found here.

Simple Example

The following example takes a list of integers and multiplies, adds, or finds the maximum between them.

#include <gears/optparse.hpp>
#include <numeric>

namespace opt = gears::optparse;

int main(int argc, char** argv) {
    opt::option_parser parser = {
        { "sum", "calculates the sum of the digits" },
        { "product", 'p', "calculates the product of the digits" },
        { "max", "calculates the maximum digit (default)" }
    };
    parser.description = "Calculates the maximum, sum, or product of integers";
    auto&& args = parser.parse(argv, argv + argc);
    if(args.positional.empty()) {
        parser.error("no input digits given");
    }

    auto&& sum = [](int total, const std::string& str) { return total + std::stoi(str); };
    auto&& prod = [](int total, const std::string& str) { return total * std::stoi(str); };
    auto&& max = [](const std::string& lhs, const std::string& rhs) {
        return std::stoi(lhs) < std::stoi(rhs);
    };

    auto&& begin = args.positional.begin();
    auto&& end = args.positional.end();

    if(args.options.is_active("sum")) {
        std::cout << std::accumulate(begin, end, 0, sum) << '\n';
    }
    else if(args.options.is_active("product")) {
        std::cout << std::accumulate(begin, end, 1, prod) << '\n';
    }
    else {
        std::cout << *std::max_element(begin, end, max) << '\n';
    }
}

Assuming that the following code is stored under dev.cpp and executed under Linux, then you'd get the following nicely formatted help message:

$ ./dev --help
usage: ./dev [options...]

Calculates the maximum, sum, or product of integers

options:
    -h, --help        shows this message and exits
        --sum         calculates the sum of the digits
    -p, --product     calculates the product of the digits
        --max         calculates the maximum digit (default)

When the appropriate arguments are passed, you get the sum, product, or maximum of the elements.

$ ./dev --sum 10 19 20 11
60
$ ./dev -p 10 19 20 11
41800
$ ./dev 10 19 20 11
20

If an error is spotted then the program prints the error and elegantly exits like so:

$ ./dev
usage: ./dev [options...]
./dev: error: no input digits given
$ ./dev –other
usage: ./dev [options...]
./dev: error: unrecognised option '–other'