qflags

Simple cross-platform C++ command-line parsing library

Overview

qflags uses command-line syntax similar but not equivalent to getopt and getopt_long. qflags can be used as a header-only library or compiled into a static library. Google Test is included as a submodule and will be used to compile and execute gtest binaries if available.

Getting Started

Requirements

The following build systems are supported via CMake:

• Visual Studio 2013
• Visual Studio 2015
• Visual Studio 2015 Clang/C2*
• GCC (MinGW, Unix)

Other build systems are untested and YMMV.

Usage

There are three 'framework' classes:

class name	description
command_line	Normalizes a command-line from argc, argv or args parameters.
argument	Base object representing an argument and its value in the command-line.
parser	Holds references to argument objects and populates their data using a command_line.

A trivial program using qflags:

#include <qflags/qflags.h>
#include <cstdio>

int main(int argc, char* argv[])
{
    // Normalize command-line.
    auto command_line = qflags::command_line(argc, argv);
    // Create parser.
    auto parser = qflags::parser();
    
    // Define arguments.
    auto foo = qflags::flag("foo");
    auto bar = qflags::string_option("bar");
    
    // Add arguments to parser.
    parser.add_argument(&foo);
    parser.add_argument(&bar);
    
    // Parse.
    std::string errors;
    if (parser.parse(command_line, &errors)) {
        fprintf(stdout, "'foo' is '%s'\n", foo.value_boolean() ? "true" : "false");
        fprintf(stdout, "'bar' is '%s'\n", bar.value_string().c_str());
    } else {
        fprintf(stdout, "%s", errors.c_str());
    }
    return 0;
}

Syntax

qflags in general follows the conventions of getopt and getopt_long with some caveats.

Argument Names

• All argument types have a name string; an argument is invoked on the command-line with the argument name prefixed by two dashes, e.g. --foo.
• The parser does not check the length of an argument's name which means it is legal (however inadvisable) to define an argument with a one-character name, e.g. --f.
• If the argument is an option argument with a value then the value follows the argument name separated either by whitespace or an equals sign (=). e.g. --foo bar or --foo=bar.

Short Argument Names

• Most arguments also have an optional 'short name' which can be invoked on the command-line with the short name prefixed by a single dash, e.g. -f.
• As with the argument name, the parser does not check the length of an argument's short name. This is to allow the use of multibyte characters and multi-character grapheme clusters as short argument names.
• If the argument is an option argument with a value then the value follows the short argument name, optionally separated by whitespace. e.g. -f buzz or -fbuzz.
• When using the short argument name the equals sign is interpreted as part of the value. e.g. -f=buzz yields a value of "=buzz".
• It is not possible to define an argument with only a short name.

Subcommands

TODO :(

Argument Types

class name	value type	description
flag	bool	true if flag was specified on the command line, otherwise false. Does not accept an additional value argument.
command	bool	true if command was specified on the command line, otherwise false. Accepts and parses remaining sub-arguments.
string_option	std::string	Accepts a value argument as a string.
boolean_option	bool	Accepts a value argument interpreted as a boolean. An error is emitted if the value argument does not match one of the prescribed string values.1
integer_option	int64_t	Accepts a value argument interpreted as an integer. An error is emitted if the value argument cannot be parsed as an integer.
choice_option	std::string	Accepts a value argument as a string if it exists in a provided set of permissible values.
range_option	int64_t	Accepts a value argument as an integer if it exists in a provided set or range of permissible values.
repeated_option	<type>[]	Accepts repeated value arguments according to the parsing rules of the base option type. Argument values are accessed by index.

1: The string values "true", "True", "TRUE", and "1" evaluate to true. The string values "false", "False", "FALSE", and "0" evaluate to false. Any other string value will emit a parsing error.