argparse

Simple single-file header-only CLI option parsing for C++ that does not require a working std::regex.

Getting Started

Download the latest argparse.hpp and include it in your project.

Example

#include "argparse/argparse.hpp"

int main(int argc, char **argv) {

  // A parser object
  argparse::Parser p;

  // Program data corresponding to flags, options, and positional arguments
  bool verbose = false;
  std::string toPrint;
  std::string maybePrint;
  int repeats = 2;

  // Inform the parser of the program data. It will do type-specific conversionfrom string.

  // An option invoked with `--repeat N`
  p.add_option(repeats, "--repeat")->help("how many times to repeat first argument");
  // A flag invoked with `--verbose` or `-v`
  p.add_flag(verbose, "--verbose", "-v");
  // a required positional argument (position 1)
  p.add_positional(toPrint)->required();
  // an optional positional argument (position 2)
  auto psnl = p.add_positional(maybePrint);

  // If there was an error during parsing, report it.
  if (!p.parse(argc, argv)) {
    std::cerr << p.help();
    exit(EXIT_FAILURE);
  }

  // If help was requested, print it
  if (p.need_help()) {
    std::cerr << p.help();
    return 0;
  }

  // Execute the program logic
  if (verbose) {
    std::cerr << "about to print '" << toPrint << "' " << repeats << " times";
    if (psnl->found()) {
      std::cerr << ", then '" << maybePrint << "'";
    }
    std::cerr << std::endl;
  }

  for (int i = 0; i < repeats; ++i) {
    std::cout << toPrint;
  }
  if (psnl->found()) {
    std::cout << maybePrint;
  }
  std::cout << std::endl;

  return 0;
}

Adding Options

Options may be int32_t, int64_t, size_t, float, double, or std::string. They are invoked like --long-opt value (not --long-opt=value) or -s value, if provided. If they are not present, the value is not modified.

int var1 = 3; // a default value for var1
argparse::Parser p;
p.add_option(var1, "--long-opt");
p.add_option(var2, "--long-opt, -s");
p.add_option(var3, "--long-opt, -s")->help("a demo option");

Adding Flags

Flags are always bools, and currently support long or short strings. The boolean variable is ALWAYS set to true if the flag is found. They are invoked like --long-flag (not --long-flag=true or --long-flag true) or -s, if provided.

argparse::Parser p;
p.add_option(flag1, "--long-flag")
p.add_option(flag2, "--another-flag", "-s");
p.add_option(flag3, "--another-flag", "-s")->help("a demo flag");

Positional Arguments

Positional arguments are added in order. Positional arguments are optional by default. Use required() to require them. add_positional() returns a PosnlBase * that may be queried with found() to see if an optional positional argument was found.

argparse::Parser p;
p.add_positional(var1)->required();
auto something = p.add_positional(var2);
if (something->found()) {
  // var2 was set
}

Anything after -- is considered a positional argument, unless -- follows an option. Here, the first -- is the value for --option and will be in s1. The second -- marks the beginning of positional arguments. and the string aa will be in s2.

argparse::Parser p;
std::string s1, s2;
p.add_option(s1, "--option");
p.add_positional(s2);
std::cerr << s1;
std::cerr << s2;

$ ./myexe --option -- -- aa
--aa

Parsing

argparse::Parser p;
// set up flags, arguments, and options
p.parse(argc, argv);

parse() returns something falsy if there is an error. Parsing modifies argc and argv to remove consumed options by default. To disable, call p->no_consume(). Parsing will silently skip unrecognized arguments. To error instead, call p->no_unrecognized().

Parser provides a constructor that takes a string description. This description will be added to the usage string.

argparse::Parser p("a demo argparse CLI app");
// set up flags, arguments, and options
p.parse(argc, argv);

Useage Strings

A --help and -h flag are automatically added. parser::need_help() returns true if either of those flags are provided. parser::help() returns a string that contains the help output.

argparse::Parser p;
if (p.need_help()) {
  std::cout << p.help();
}

cwpearson/argparse