FancyArgumentParser

A single-header, dependency-free C++ command-line argument parser.

Argparse-style ergonomics for C++ — named & positional arguments, type casting, choices, value validators, defaults, auto-generated help, and Python-like keyword arguments in C++20.

Tutorial · Examples · Class reference

---

Why

Drop one header into your project and get a fully featured argument parser — no submodules, no CMake packages, no linking. Everything lives in argparse.h.

Features

• 🧩 Single header, zero dependencies — just #include "argparse.h".
• 📦 C++20 module — optional import argparse; via argparse.ixx.
• 🏷️ Named and positional arguments, freely mixed in any order.
• 🔢 Typed values — int, long long, double, bool, and string.
• 🎚️ Flexible arity — fixed counts, or Python-style '?' (zero-or-one), '*' (zero-or-more) and '+' (one-or-more), plus the matching kZeroOrOneArgCount / kAnyArgCount / kFromOneToInfiniteArgCount constants.
• ✅ Validation — required/optional, value choices, numeric SetRange, SetPositive, filesystem checks (SetExistingFile), and custom SetValidator predicates.
• 🔗 Variable binding — BindTo(&var) writes parsed values straight into your own variables.
• 🎯 By-name getters — obj.GetAsInt("count") straight off the parsed result.
• 📖 Auto-generated help & usage, with custom epilogue and overridable usage line.
• 🔤 Long-option abbreviations (--verb → --verbose when unambiguous).
• ⚙️ Configurable — custom prefix characters, ignore-unknown args, custom namespace.
• 🆕 Three declaration styles, including Python-like keyword arguments in C++20.
• 🧪 Tested across Linux, macOS and Windows on C++17/20/23.

Quick start

Copy argparse.h into your project — that's the whole installation.

#include <iostream>
#include "argparse.h"

int main(int argc, char** argv)
{
    auto parser = argparse::ArgumentParser("greet").SetDescription("A tiny greeter");

    parser.AddArgument(argparse::CreateNamedArgument("n", "name", 1,
        argparse::ArgTypeCast::e_String, true).SetHelp("Who to greet"));
    parser.AddArgument(argparse::CreateNamedArgument("c", "count", 1,
        argparse::ArgTypeCast::e_int, false).SetDefault(1).SetHelp("How many times"));

    auto obj = parser.ParseArgs(argc, argv);
    if (!obj.IsArgValid())
    {
        std::cout << obj.GetErrorString() << "\n" << parser.GetHelp(80) << std::endl;
        return 1;
    }

    auto name = obj.GetArg("name");
    for (int i = 0; i < obj.GetArg("count").GetAsInt(); ++i)
        std::cout << "Hello, " << name.GetAsString() << "!\n";
    return 0;
}

$ c++ -std=c++17 greet.cpp -o greet
$ ./greet --name World --count 2
Hello, World!
Hello, World!

Three ways to declare an argument

Pick whichever reads best — they build the same argument.

// 1. Fluent setters
parser.AddArgument(argparse::CreateNamedArgument()
    .SetShortName("n").SetLongName("numbers")
    .SetType(argparse::ArgTypeCast::e_int)
    .SetAnyNumberOfArgumentsButAtLeastOne());

// 2. Positional factory arguments
parser.AddArgument(argparse::CreateNamedArgument("n", "numbers",
    argparse::kFromOneToInfiniteArgCount, argparse::ArgTypeCast::e_int));

// 3. Keyword style — Python-like, needs C++20 designated initializers
parser.AddArgument(argparse::CreateNamedArgument({
    .shortName = "n",
    .longName  = "numbers",
    .nargs     = argparse::kFromOneToInfiniteArgCount,
    .type      = argparse::ArgTypeCast::e_int}));

Note: every argument is required by default — call SetRequired(false) (or set required = false) to make one optional.

Short names may be written as a single char ('n') as well as a string ("n"), and arity accepts a Python-style char in place of a constant:

// 'c' short name, '?' == zero-or-one value (same as kZeroOrOneArgCount)
parser.AddArgument(argparse::CreateNamedArgument('c', "count", '?')
    .SetType(argparse::ArgTypeCast::e_int).SetDefault(1));

// '+' == one-or-more, '*' == zero-or-more
parser.AddArgument(argparse::CreatePositionalArgument("files", '+'));

Binding values to variables

Instead of pulling each value out with GetArg(name).GetAsX(), you can bind an argument directly to one of your variables with BindTo(&var). After a successful ParseArgs(), the parsed value is written straight into it.

int         count = 1;          // initial value doubles as the default
std::string name;
std::vector<int> ids;

auto parser = argparse::ArgumentParser("prog");
parser.AddArgument(argparse::CreateNamedArgument("c", "count", 1).BindTo(&count));
parser.AddArgument(argparse::CreateNamedArgument("n", "name",  1).BindTo(&name));
parser.AddArgument(argparse::CreateNamedArgument("i", "ids")
    .SetAnyNumberOfArgumentsButAtLeastOne().BindTo(&ids));

auto obj = parser.ParseArgs(argc, argv);
if (obj.IsArgValid())
{
    // count, name and ids are already populated — no GetArg(...) calls needed.
}

BindTo works for every supported type (bool, int, long long, double, std::string) and their std::vector<> variants, and is available in C++11 onward.

• Type is inferred from the bound variable, so you don't need a separate SetType() call (and shouldn't add one that contradicts it).
• The bound variable must outlive the ParseArgs() call.
• If an optional argument is absent (and has no default), its bound variable is left untouched — so its initial value acts as the default.
• Bindings are applied only on a successful parse; a failed parse never writes through them.

Validating values

Beyond choices, an argument can carry a validator that each parsed value must pass; a failing value makes ParseArgs return an invalid result with a message.

// Numeric range (also sets the type for you)
parser.AddArgument(argparse::CreateNamedArgument('p', "port")
    .SetRange(1, 65535));

// Strictly positive
parser.AddArgument(argparse::CreateNamedArgument('r', "ratio")
    .SetType(argparse::ArgTypeCast::e_double).SetPositive());

// Filesystem checks (available when <filesystem> is, i.e. C++17+)
parser.AddArgument(argparse::CreateNamedArgument('i', "input")
    .SetExistingFile());

// Any custom predicate, with an optional error message
parser.AddArgument(argparse::CreateNamedArgument('m', "mode")
    .SetValidator([](const std::string& v){ return v == "fast" || v == "safe"; },
                  "mode must be 'fast' or 'safe'"));

Built-in validators include SetRange (int / long long / double, as (lo, hi) or (max)), SetPositive, SetNonNegative, and the path checks SetExistingFile, SetExistingDirectory, SetExistingPath, SetNonexistentPath.

Mixing positional and named arguments

Positional and named arguments can be declared and passed in any order — the parser assigns bare values to positionals left to right while pulling named options out of the stream.

auto parser = argparse::ArgumentParser("cp");
parser.AddArgument(argparse::CreatePositionalArgument("src"));
parser.AddArgument(argparse::CreatePositionalArgument("dst"));
parser.AddArgument(argparse::CreateNamedArgument('f', "force",
    0, argparse::ArgTypeCast::e_bool, false));   // a flag

// all equivalent:  a b --force  |  --force a b  |  a --force b
auto obj = parser.ParseArgs(std::vector<std::string>{ "a", "--force", "b" });
std::string src = obj.GetAsString("src");   // "a"
std::string dst = obj.GetAsString("dst");   // "b"

Reading results by name

After a successful parse you can read values straight off the result by argument name, without going through GetArg(...) first:

int                       n     = obj.GetAsInt("count");
double                    ratio = obj.GetAsDouble("ratio");
std::string               name  = obj.GetAsString("name");
const std::vector<int>&   nums  = obj.GetAsVecInt("numbers");

The longer obj.GetArg("count").GetAsInt() form still works and is handy when you want to inspect the Argument itself (e.g. GetArgumentExists()).

Configuring the parser

ArgumentParser can be built from a ParserSpec aggregate, which collects the parser-level options in one place (the counterpart of the keyword-style argument specs):

auto parser = argparse::ArgumentParser(argparse::ParserSpec{
    .name        = "cptool",
    .description = "Copy files",
    .prefixChars = '-',
    .addHelp     = true,
    .allowAbbrev = false});

The designated-initializer form needs C++20; the same struct also works with ordinary aggregate initialization in C++11/14/17.

Using it as a C++20 module

On toolchains that support C++20 modules (MSVC, GCC ≥ 14) you can consume the library through import instead of #include:

import argparse;

int main(int argc, char** argv)
{
    argparse::ArgumentParser parser("demo");
    // ... same API as the header ...
}

Add argparse.ixx to your build as a module interface unit; it wraps argparse.h and re-exports the public API. The header remains fully usable on its own, so nothing changes for #include users. Define ARGPARSE_NAMESPACE_NAME when building the module to rename the exported namespace, exactly as with the header.

Requirements

• A C++11 compiler or newer. The library is continuously tested on C++17, C++20 and C++23 across Linux, macOS and Windows.
• The std::any-based Get() accessor is available from C++17 onward; the typed getters (GetAsInt(), GetAsVecInt(), …) work in every standard.
• Designated-initializer (keyword) argument construction needs C++20.

Building the tests

The tests live under tests/ and are never included by the header, so consumers can ignore them entirely.

cmake -S tests -B build
cmake --build build
ctest --test-dir build --output-on-failure

Override the standard with -DCMAKE_CXX_STANDARD=20 (or 23).

Documentation

• 📘 Tutorial — step-by-step introduction.
• 📗 Examples — flags, choices, positional/named mixes, bool, ranges, keyword args, and more.
• 📙 Class reference — full API overview.
• 📓 About — project background.

License

Released under the MIT License — see the header of argparse.h for the full text. © 2021 simfeo.