Skip to content

Classes description

Jump to bottom
idimus edited this page Jul 10, 2026 · 2 revisions

This page documents the public API of FancyArgumentParser. Everything lives in a single header and in one namespace (argparse by default — see Configuration macro).

#include "ArgParse/argparse.h"   // or  #include <argparse.h>

A typical program: build an ArgumentParser, add Arguments to it, call ParseArgs, then read the results from the returned ArgumentsObject.

Contents

Enumerations

enum class ArgTypeCast

The type an argument's values are parsed and stored as.

Value Parsed as
e_String std::string (the default; use it for any type not listed)
e_int int
e_longlong long long
e_double double
e_bool bool — accepts true/True/TRUE and false/False/FALSE

Constants

Constant Value Meaning (as an argument count)
kAnyArgCount -1 zero or more values
kFromOneToInfiniteArgCount -2 one or more values

Any non-negative integer is also a valid count: 0 makes a flag (no value), 1 a single value, N exactly N values.

Factory functions

Free functions that return an Argument. Pass the result to ArgumentParser::AddArgument. Each has three forms — positional parameters, fluent setters, or an aggregate spec struct.

Argument CreateNamedArgument(const std::string& shortName = "",
                             const std::string& longName = "",
                             int argsCount = 1,
                             ArgTypeCast argType = ArgTypeCast::e_String,
                             bool required = true,
                             const std::string& help = "");

Argument CreatePositionalArgument(const std::string& positionalName = "",
                                  int argsCount = 1,
                                  ArgTypeCast argType = ArgTypeCast::e_String,
                                  bool required = true,
                                  const std::string& help = "");

// Keyword-style overloads (see Spec structs)
Argument CreateNamedArgument(const NamedArgSpec& spec);
Argument CreatePositionalArgument(const PositionalArgSpec& spec);

Spec structs

Aggregates for keyword-style construction. With C++20 designated initializers they read like Python's add_argument; in earlier standards they still work with plain aggregate initialization. Fields you omit take their defaults.

struct NamedArgSpec {
    std::string shortName = "";
    std::string longName  = "";
    int         nargs     = 1;
    ArgTypeCast type      = ArgTypeCast::e_String;
    bool        required  = true;
    std::string help      = "";
};

struct PositionalArgSpec {
    std::string name     = "";
    int         nargs     = 1;
    ArgTypeCast type      = ArgTypeCast::e_String;
    bool        required  = true;
    std::string help      = "";
};
parser.AddArgument(argparse::CreateNamedArgument({
    .longName = "numbers",
    .nargs    = argparse::kFromOneToInfiniteArgCount,
    .type     = argparse::ArgTypeCast::e_int}));

class Argument

Describes one argument. Every setter returns Argument&, so calls can be chained. Build an Argument with the factory functions, not by constructing it directly.

Method Description
Argument& SetShortName(const std::string&) Short name, used with a single prefix (e.g. -n).
Argument& SetLongName(const std::string&) Long name, used with a double prefix (e.g. --numbers).
Argument& SetPositionalName(const std::string&) Name of a positional argument (no prefix on the command line).
Argument& SetType(ArgTypeCast) Value type. Defaults to e_String.
Argument& SetRequired(bool) Whether the argument must be present. All arguments are required by default.
Argument& SetHelp(const std::string&) Help text shown in the generated help.
Argument& SetNumberOfArguments(int) Exact/among value count; accepts kAnyArgCount / kFromOneToInfiniteArgCount.
Argument& SetAnyNumberOfArguments() Shorthand for kAnyArgCount (zero or more).
Argument& SetAnyNumberOfArgumentsButAtLeastOne() Shorthand for kFromOneToInfiniteArgCount (one or more).
Argument& SetArgumentIsFlag() Zero values — the argument is a flag (present or absent).
Argument& SetChoices(const std::vector<std::string>&) Restrict values to a set (string overload).
Argument& SetChoices(std::initializer_list<const char*>) Same, for braced string-literal lists like {"+","-"}.
Argument& SetChoices(const std::vector<int>&) Choices for e_int.
Argument& SetChoices(const std::vector<long long>&) Choices for e_longlong.
Argument& SetChoices(const std::vector<double>&) Choices for e_double.
Argument& SetDefault(...) Value used when the argument is omitted. Overloads for bool, int, long long, double, std::string, and std::vector of each.

class ArgumentParser

The main entry point. Configure it, add arguments, then parse.

Construction & configuration

Method Description
ArgumentParser(const std::string& name) Construct with a program name.
ArgumentParser& SetDescription(const std::string&) Text shown after the usage line.
ArgumentParser& SetEpilogue(const std::string&) Text shown at the end of the help.
ArgumentParser& SetUsage(const std::string&) Replace the auto-generated usage line with your own.
ArgumentParser& SetAddHelp(bool) Add the automatic -h/--help option (on by default).
ArgumentParser& SetPrefixChars(char) Option prefix character (default -).
ArgumentParser& SetAllowAbbrev(bool) Accept unambiguous long-option prefixes, e.g. --verb for --verbose (on by default).
ArgumentParser& SetIgnoreUnknownArgs(bool) Skip unrecognised options instead of failing (off by default).

All configuration setters return ArgumentParser& for chaining.

Adding arguments & parsing

Method Description
void AddArgument(const Argument&) Register an argument. May throw std::runtime_error if the argument is malformed (a programmer error).
ArgumentsObject ParseArgs(int argc, char** argv) Parse from main's arguments (skips argv[0]).
ArgumentsObject ParseArgs(const std::vector<std::string>& args) Parse from a vector of tokens (no program name). Handy for tests.
std::string GetHelp(size_t width = 80, size_t nameWidthPercent = 30) Build the help text. width is the terminal width; nameWidthPercent is the share used for the names column.

class ArgumentsObject

The result of ParseArgs.

Method Description
bool IsArgValid() const true if parsing succeeded. Always check this first.
const std::string& GetErrorString() Human-readable message describing the first error (empty on success).
ArgumentParsed GetArg(const std::string& name) Look up a parsed argument by short, long, or positional name.
size_t ParsedArgsCount() const Number of successfully parsed arguments.

class ArgumentParsed

A single parsed argument, returned by ArgumentsObject::GetArg.

Method Description
bool GetArgumentExists() Whether the argument was present (or has a default).
size_t GetArgumentCount() Number of values parsed for this argument.
bool GetAsBool() const First value as bool.
int GetAsInt() const First value as int.
long long GetAsLongLong() const First value as long long.
double GetAsDouble() const First value as double.
std::string GetAsString() const First value as std::string.
std::vector<bool> GetAsVecBool() const All values as a bool vector.
std::vector<int> GetAsVecInt() const All values as an int vector.
std::vector<long long> GetAsVecLongLong() const All values as a long long vector.
std::vector<double> GetAsVecDouble() const All values as a double vector.
std::vector<std::string> GetAsVecString() const All values as a std::string vector.
std::any Get() The value(s) as std::any (single value or vector, depending on count). Requires C++17.

The scalar getters throw std::out_of_range if the argument holds no value — guard them with GetArgumentExists() when the argument is optional and has no default.

Configuration macro

Macro Effect
ARGPARSE_NAMESPACE_NAME Renames the library namespace. Define it before including the header. Defaults to argparse. 
#define ARGPARSE_NAMESPACE_NAME cli
#include "ArgParse/argparse.h"
// now use cli::ArgumentParser, cli::CreateNamedArgument, ...

Behaviour notes

  • Required by default. Every argument — named and positional — is required unless you call SetRequired(false) (or set required = false). This differs from Python's argparse, where named options are optional by default.
  • Positionals before named. On the command line, pass positional arguments before named ones. The parser collects positionals first.
  • Error model. AddArgument throws on a malformed definition (a programmer mistake, caught during development). Bad user input is never thrown — it is reported through IsArgValid() / GetErrorString().
  • Standards. The library works with C++11 and later; the std::any-based Get() needs C++17, and keyword-style designated initializers need C++20.

For runnable programs covering every feature, see the Examples.

Clone this wiki locally