The Argument Parser

Introduction

This is TAP, a library for command line argument parsing ala get_opt_long(). It is a header-only library with a bunch of templated classes that ought to make argument parsing simple. The main reasons for the existence of this library:

• Simple to install, drop in the headers and done;
• Ability to store argument variables directly into passed variables, or internally in the argument data;
• Attempt to somewhat separate the notion of constraints;
• Something that uses a bit more recent C++ dialect (C++14);
• It does mostly the same as anything else, but slightly different.

Try before you buy, check some of the examples, and otherwise look at for instance boost::program_options, TCLAP, get_opt() (ha), "The Lean Mean C++ Option Parser", cpp-optparse, or just check http://stackoverflow.com/questions/865668/parse-command-line-arguments.

Installation

As this is a header-only library, no install is necessary. Just drop the directory 'tap' with all headers somewhere in your include path, and all should be fine.

Usage

To use the library, first add a

#include <tap/Tap.h>

to your sources, then simply code away. All members of TAP are defined in the TAP namespace.

Quickstart:

#include <tap/Tap.h>
#include <iostream>

int main(int argc, const char* argv[]) {
    TAP::Argument badExit("If set, exit with non-zero status", 'x', "badexit");
    TAP::ArgumentParser parser(badExit);
    try {
        parser.parse(argc, argv);
    } catch (TAP::exception& e) {
        std::cerr << e.what() << std::endl;
        return 1;
    }
    if (badExit) {
        // The argument was set
        std::cout << "Just, why?" << std::endl;
        return 1;
    }
    return 0;
}

Tutorial and examples

Argument parsing starts with defining a number of TAP::Argument instances, adding them to an TAP::ArgumentParser, and passing along the actual program arguments (as received from main()) to the parser. If all goes well, you can read in the parsed data from the arguments, otherwise an TAP::exception will be thrown.

The examples below assume TAP_AUTOFLAG has been defined, see Configuration for details.

Defining arguments

At the basic level, an argument consists of a description, and zero or more aliases. Aliases can be used to name the argument on the command line, either as a flag or as a name (see TAP::ArgumentParser for details). One particular remark about aliases: If an argument is created without an alias, it is marked as positional. Any alias defined later does not change this. This allows positional arguments to be defined, that can also be accessed via a name or flag.

The description can be used to define aliases as well. To do so, mark the flags or names to use in the description (see TAP::Argument::parse_description()). You can use this to save on typing when defining arguments.

Multiple argument classes exist that can be used, in short they are

• Argument: Simple argument class that can only be marked as set. They always have an alias associated with them.

  // These two arguments are equivalent
  TAP::Argument a1("Show this help text", 'h', "help");
  TAP::Argument a2("Show this &help text");

• VariableArgument: Argument that can be assigned a value on the command line, which is stored in a variable that is given to the argument.

  int optimization = 1; // This also defines the default value.
  TAP::VariableArgument<int> optimizeLevel("Set &optimization level", optimization);

• ValueArgument: Like VariableArgument, but stores the value internally.

  // Initialize with default value 1
  TAP::ValueArgument<int> optimizeLevel("Set &optimization level", 1);

• MultiVariableArgument, MultiValueArgument: Like above, but can occur multiple times on the command line, and each occurrence is stored separately. An std::vector is used to store these values.

  TAP::MultiValueArgument<std::string> includes("%Include these files");
  ...
  const std::string& firstFile = includes.value()[0];

• ConstArgument: Like Argument, but when it occurs, writes a constant value to a variable that is given to the argument.

  enum class LogLevel {DEBUG, INFO, ERROR};
  LogLevel logLevel = LogLevel::INFO; // default to info
  TAP::ConstArgument<LogLevel> debugLevel("Set &debug level", logLevel, LogLevel::DEBUG);
  TAP::ConstArgument<LogLevel> infoLevel("Set &info level", logLevel, LogLevel::INFO);
  TAP::ConstArgument<LogLevel> errorLevel("Set &error level", logLevel, LogLevel::ERROR);

• SwitchArgument: Like Argument, but keeps track of a boolean value, either internally or externally, that is switched each time it occurs.

  bool do_daemonize = false; // default to false
  TAP::SwitchArgument daemonize("Fork to background", 'd', do_daemonize);
  // restart defaults to true, so if set will switch to false
  // note: this is a terrible way to interact
  TAP::SwitchArgument restart("Do not &restart on error", true);

Required arguments and argument counts

By default, all arguments are optional, and can occur at most once. To change this behavior, each argument has the following functions:

• set_required() : Require the argument to occur at least once
• many() : Allow the argument to occur an unbounded amount of times
• min(N) : Require the argument to occur at least N times
• max(N) : Allow the argument to occur at most N times

Regular arguments by default are optional and can occur at most once. Multi* arguments can occur many times. Note that for most TypedArgument types (except Multi*), if the argument is allowed to occur multiple times, its value is overwritten on each occurrence.

A common occurrence of arguments that are allowed to occur multiple times, but sometimes limited, are verbosity or debugging level arguments. For example:

TAP::Argument verbosity("Set the verbosity level", 'v', "verbose");
verbosity.max(3); // alternatively: many()
...
if (verbosity) {
    unsigned int verbosityLevel = verbosity.count();
}

Note that there is a (small) semantic difference between a required argument and the minimum number of occurrences. If required() is true, this only means the argument has to occur somewhere. The min() value dictates how many times. If required() is false, the argument is also alowed to be absent, even if min is not zero. In fact, min is required to be always at least 1.

Argument callbacks

It is possible to assign a callback to an TAP::Argument that is called whenever the argument is set. For example:

TAP::Argument help("Show this &help text");
TAP::ArgumentParser parser(help);
help.check([&parser](const TAP::Argument&) -> void {
    std::cout << parser.help() << std::endl; exit(1);
});

For details see TAP::Argument::check() and TAP::ArgumentCheckFunc.

Similarly, TAP::TypedArgument also allows for a callback with the value that was set, for example:

TAP::ValueArgument<int> answer("Set the &answer");
TAP::ArgumentParser parser(answer);
answer.check([&parser](const TAP::TypedArgument<int>&, int val) -> void {
    if (val != 42) {
        throw TAP::exception("That is not the answer");
    }
});

For details see TAP::TypedArgument::check() and TAP::TypedArgumentCheckFunc.

Argument constraints

Every now and then some arguments can only occur in certain combinations or have some sort of constraint associated with them (aside from the number of occurrences allowed or required, see Required arguments and argument counts). To specify this, arguments can be added (recursively) into TAP::ArgumentConstraint instances, which specify a certain constraint on the occurrences of arguments relative to each other. Most commonly, exactly one argument must be selected out of a group of many.

To specify such a constraint, create an instance of TAP::ArgumentConstraint, templated to TAP::ConstraintType to specify which constraint, and add the constrained arguments. For example:

TAP::Argument left("Turn &left");
TAP::Argument right("Turn &right");
TAP::ArgumentConstraint<TAP::ConstraintType::One> dir(left, right);
TAP::Argument help("Show this &help text");
TAP::ArgumentParser parser(dir, help);

In this example, left and right cannot be set both at the same time. Should either left or right be selected (so selecting neither is invalid), set the constraint as required with set_required().

Note: Be careful when adding arguments that are required to constraints with an upper bound on the number of allowed arguments (such as TAP::ConstraintType::One). This can lead to situations where the constraint can never be satisfied, as all of its arguments are required, but the constraint prohibits this.

Operators

For the common case of mutually exclusive arguments, the hat operator (binary XOR) has been defined for arguments to create a TAP::ConstraintType::One constraint of the given arguments. For example:

TAP::Argument left("Turn &left");
TAP::Argument right("Turn &right");
TAP::Argument help("Show this &help text");
TAP::ArgumentParser parser(left ^ right, help);

Similarly, the OR operator (|) is defined for TAP::ConstraintType::Any, and the AND operator (&) is defined for TAP::ConstraintType::All.

Furthermore, unary operators + and - set an argument respectively as required or optional. Thus, in the above example, to require exactly left or right to be set, you can use:

TAP::ArgumentParser parser(+(left ^ right), help);

Parsing arguments

Parsing arguments is relatively straight-forward. After defining all arguments and an argument parser, with the arguments added to the parser, simply invoke TAP::ArgumentParser::parse and done. If an error occurs, an exception of the type TAP::exception (or a subclass thereof) will be thrown.

int main(int argc, char** argv) {
    TAP::Argument help("Show this &help text");
    TAP::Argument version("Show &version information");
    TAP::ArgumentParser parser(help, version);
    parser.parse(argc, argv);
    if (help) {
        std::cout << parser.help() << std::endl;
    } else if(version) {
        std::cout << "FIXME" << std::endl;
    }
    return 0;
}

Arguments can be added either in the constructor, or using the TAP::ArgumentParser::add() method.

Argument groups

To group arguments (useful mostly for the help text) a TAP::ArgumentSet can be created (similar to a constraint), with a given name. When added to the parser, its children are grouped separately in the help text.

Argument testing and value retrieval

To determine if an argument is set, converting to bool is possible, e.g.

TAP::Argument myArg("&test");
if (myArg) {
    ...
}

Keep in mind that for arguments that actually store a bool, this is not the same as its value.

To get the number of occurrences, see the TAP::Argument::count() method. For TAP::TypedArgument instances, the value can be retrieved using TAP::TypedArgument::value(). Note that for Multi valued arguments, the value is automatically set to a vector.

Configuration

TAP allows for some configuration in the main header file. The following settings alter some of its behavior:

• TAP_STREAMSAFE : When defined, the default stream operator will defer writing to a stored variable until the input is considered valid. This prevents the variable from being modified if the input is not valid. Note that this requires stored variables to allow copy or move construction.
• TAP_AUTOFLAG : When defined, try to parse the description string to find flag and/or name markers. See also TAP::Argument::parse_description().

Aside from these options, other defines allow some of the syntax to be tweaked (see Tap.h for more details):

• TAP_FLAG : Defines the string for TAP::flagStart
• TAP_NAME : Defines the string for TAP::nameStart
• TAP_NAMEDELIMITER : Defines the string for TAP::nameDelim
• TAP_SKIP: Defines the string for TAP::skip

Quirks

Though the library is intended to use relatively easy to use, it may not always do what is expected. Some quirks are listed here:

• Arguments are stored as copies inside the parser, constraints and groups. Thus, adding an argument to the parser and modifying it afterwards does not work as one may expect. However, copies of arguments will share the same occurrence counter and value, thus adding an argument without modification to multiple constraints will still work.
• No argument duplication checks are made. If you add an argument (or two different arguments) with the same alias to the parser, constraint or group, the library will not generate an error. This is useful for the case where an argument occurs in multiple constraints (as they are stored as copies, see above point), but may yield surprising results otherwise. The parser will try to find arguments in the order they were added, so the first added argument has priority. However, if that argument is already set its maximum amount of times, it will look for the next. Only if that fails an error is generated.
• The point above also implies something else: It is possible to add multiple positional arguments that can occur many times. In that case, only the first argument added will receive values.

Known issues

• VariableArgument overload resolution kind of wonky
• Help text argument sorting and duplicates, also no skip marker
• Not particularly high performance