/// Whether the token is a \c T. Null means anything goes, which is the default.

bool (*check)(std::string_view) = nullptr;

/// The name used in diagnostics and in the help text. Must be a literal, since

/// it is held rather than copied.

const char *name = nullptr;

if constexpr (std::is_signed_v<T>) {

int64_t v;

if (!detail::parse_signed(token, &v, int64_t(std::numeric_limits<T>::min()),

int64_t(std::numeric_limits<T>::max()))) {

return false;

}

*out = T(v);

} else {

uint64_t v;

if (!detail::parse_unsigned(token, &v, uint64_t(std::numeric_limits<T>::max()))) {

return false;

}

*out = T(v);

}

return true;

public:

/// How many tokens it takes.

enum Arity {

/// Exactly one.

Single,

/// One or more, also called greedy. Leaves enough tokens for the required arguments

/// after it, so \c copy \c \<src\>... \c \<dest\> works.

Multiple,

/// Everything left, options included, which is why nothing may follow one. Where it

/// starts is where option reading stops, so this is how a program spells its own

/// terminator.

///

/// Where it starts is where the argument before it was filled. Where it is the

/// first argument there is none, so it starts at the first token not written as

/// an option, which is what lets a wrapper take options of its own:

/// \c run \c -u \c root \c ls \c -l gives \c -u to \c run and \c -l to \c ls.

///

/// \note Required like any other argument, so an empty tail wants optional().

Remainder,

};

/// Answers whether \a token is acceptable, and says why in \a error when it is not.

///

/// It may be called repeatedly with the same token, including while the command tree is

/// validated. It should have no observable side effects and should give the same answer

/// without depending on how many times it has been called or on mutable external state.

using Validator = std::function<bool(std::string_view token, std::string *error)>;

Argument() = default;

inline Argument(std::string name, std::string desc = {}, bool required = true)

: _name(std::move(name)), _desc(std::move(desc)), _required(required) {

}

/// The name to show in the help text, when it should differ from name().

inline Argument &metavar(std::string displayName) {

_displayName = std::move(displayName);

return *this;

}

inline Argument &required(bool on = true) {

_required = on;

return *this;

}

inline Argument &optional(bool on = true) {

_required = !on;

return *this;

}

/// The value the result gives when the argument was not given. Stored as text and

/// converted when read.

///

/// \pre It is readable as whatever type<T>() declared, and is one of the values

/// expect() allows, if either was given.

inline Argument &defaultValue(std::string value) {

_default = std::move(value);

_hasDefault = true;

return *this;

}

/// The only values this accepts, for an argument that is a choice between a few

/// words.

///

/// \pre Every one of them is readable as whatever type<T>() declared.

inline Argument &expect(std::vector<std::string> values) {

_expected = std::move(values);

return *this;

}

/// What this argument accepts beyond being readable as its type.

///

/// \pre It accepts defaultValue(), where there is one. Only what a command line wrote is

/// put past it while parsing, so a default it refuses would be handed back without

/// ever being asked about.

inline Argument &validate(Validator validator) {

_validator = std::move(validator);

return *this;

}

inline Argument &nargs(Arity arity) {

_arity = arity;

return *this;

}

inline Argument &multi(bool on = true) {

_arity = on ? Multiple : Single;

return *this;

}

/// Declares the type. Tokens are checked against it while parsing, and its name

/// appears in the help text. Without it any token is accepted.

///

/// \pre Whatever expect() was given, if anything, is readable as a \c T.

template <class T>

inline Argument &type() {

_type = detail::type_info_for<T>();

return *this;

}

inline const std::string &name() const {

return _name;

}

inline const std::string &description() const {

return _desc;

}

/// The metavar if one was given, and the name otherwise.

inline const std::string &displayName() const {

return _displayName.empty() ? _name : _displayName;

}

inline bool isRequired() const {

return _required;

}

inline bool hasDefaultValue() const {

return _hasDefault;

}

inline const std::string &defaultValue() const {

return _default;

}

inline const std::vector<std::string> &expectedValues() const {

return _expected;

}

inline const Validator &validator() const {

return _validator;

}

inline Arity arity() const {

return _arity;

}

inline const detail::value_type_info &typeInfo() const {

return _type;

}

private:

std::string _name;

std::string _desc;

std::string _displayName;

std::string _default;

std::vector<std::string> _expected;

Validator _validator;

detail::value_type_info _type;

Arity _arity = Single;

bool _required = true;

bool _hasDefault = false;

public:

/// What the option means, for the two the library answers by itself. A role brings the

/// usual spellings and description, and lets a caller ask by role rather than by

/// spelling.

///

/// The set is closed, and it is these two because these two are what the library does

/// something with. A role for a switch it only carries the spelling of would be a

/// second way of writing Option({"-V", "--verbose"}, "Print more information").

///

/// \note A role says nothing about scope, which is recursive(), nor about where an option

/// sits in the help text, which is where it was declared.

enum Role {

NoRole,

Version,

Help,

};

/// How much of a short token the parser may take for this option, so that \c -O2 or

/// \c -DKEY=VALUE can be one token rather than two.

enum ShortMatch {

/// \c -D and its value are separate tokens.

NoShortMatch,

/// A single letter may be followed by the value, as in \c -O2.

ShortMatchSingleLetter,

/// A single character, letter or not.

ShortMatchSingleChar,

/// The whole token after the option's own, as in \c -DKEY=VALUE.

ShortMatchAll,

};

/// The highest level among the options given decides. This is what lets \c --help be

/// answered on a command line that is missing everything it requires.

///

/// ###QUESTION: Should automatic activation and exclusivity be split from missing-value

/// priority? This enum prevents combining those policies and orders unrelated values.

enum Prior {

NoPrior,

/// Its own missing arguments are not an error.

IgnoreMissingArguments,

/// Nothing missing anywhere is an error.

IgnoreMissingSymbols,

/// Set it when nothing else was given at all.

AutoSetWhenNoSymbols,

/// Giving it means no arguments may be given.

ExclusiveToArguments,

/// Giving it means no other options may be given.

ExclusiveToOptions,

/// Giving it means nothing else may be given.

ExclusiveToAll,

};

Option() = default;

inline Option(std::vector<std::string> tokens, std::string desc = {})

: _tokens(std::move(tokens)), _desc(std::move(desc)) {

}

inline Option(std::initializer_list<std::string> tokens, std::string desc = {})

: Option(std::vector<std::string>(tokens), std::move(desc)) {

}

inline Option(std::string token, std::string desc = {})

: Option(std::vector<std::string>{std::move(token)}, std::move(desc)) {

}

/// Deliberately not explicit, so that \c addOptions({Option::Help}) reads the way it

/// does. Empty tokens take the usual spelling for the role.

inline Option(Role role, std::vector<std::string> tokens = {}, std::string desc = {})

: _tokens(tokens.empty() ? defaultTokens(role) : std::move(tokens)),

_desc(desc.empty() ? defaultDescription(role) : std::move(desc)), _role(role) {

}

/// Adds an argument. An option's argument needs no description of its own.

inline Option &arg(std::string name, bool required = true) {

return arg(Argument(std::move(name), {}, required));

}

inline Option &arg(Argument argument) {

_args.emplace_back(std::move(argument));

return *this;

}

inline Option &required(bool on = true) {

_required = on;

return *this;

}

/// Whether a value may be stuck to the spelling, \c -Dfoo rather than \c -D \c foo.

///

/// \note A permission rather than a promise. One token carries one value, so an option

/// that takes no argument, takes an optional one, takes more than one, or whose

/// one argument is greedy is never matched this way whatever is set here. Written

/// out with a space they all work.

inline Option &shortMatch(ShortMatch rule) {

_shortMatch = rule;

return *this;

}

inline Option &prior(Prior level) {

_prior = level;

return *this;

}

/// In scope for every command below this one as well as for this one.

///

/// Without it an option can be given only where the command declaring it is the one that

/// was reached, since every option is written after its own command.

inline Option &recursive(bool on = true) {

_recursive = on;

return *this;

}

/// How many times the option may be given, zero meaning without limit.

///

/// What repeats is the whole occurrence: every time the option is written it reads its

/// arguments again, into a set of its own that OptionResult::at() hands back. How many

/// values one argument takes within one occurrence is a different question, and

/// Argument::multi() is where it is asked.

/// \pre \a maxOccurrence is not negative. A negative is not a smaller limit, it is one

/// the count can never reach, which reads back as no limit at all.

inline Option &multi(int maxOccurrence = 0) {

_maxOccurrence = maxOccurrence;

return *this;

}

inline const std::vector<std::string> &tokens() const {

return _tokens;

}

/// The first spelling, which is the one the help text and diagnostics use.

inline const std::string &token() const {

assert(!_tokens.empty() && "an option with no spelling has no token");

return _tokens.front();

}

inline const std::string &description() const {

return _desc;

}

inline const std::vector<Argument> &arguments() const {

return _args;

}

inline bool isRequired() const {

return _required;

}

inline bool isRecursive() const {

return _recursive;

}

inline Role role() const {

return _role;

}

inline ShortMatch shortMatch() const {

return _shortMatch;

}

inline Prior prior() const {

return _prior;

}

inline int maxOccurrence() const {

return _maxOccurrence;

}

/// What a role says about itself in the help text when nothing else was given.

static inline std::string defaultDescription(Role role) {

switch (role) {

case Help:

return "Show this help and exit";

case Version:

return "Show the version and exit";

default:

return {};

}

}

/// The spellings a role answers to when none were given.

static inline std::vector<std::string> defaultTokens(Role role) {

switch (role) {

case Help:

return {"-h", "--help"};

case Version:

return {"-v", "--version"};

default:

return {};

}

}

private:

std::vector<std::string> _tokens;

std::string _desc;

std::vector<Argument> _args;

Role _role = NoRole;

ShortMatch _shortMatch = NoShortMatch;

Prior _prior = NoPrior;

int _maxOccurrence = 1;

bool _required = false;

bool _recursive = false;

public:

struct Group {

std::string name;

std::vector<std::string> members;

};

inline CommandCatalogue &addCommands(std::string group, std::vector<std::string> names) {

_commands.push_back({std::move(group), std::move(names)});

return *this;

}

inline CommandCatalogue &addOptions(std::string group, std::vector<std::string> names) {

_options.push_back({std::move(group), std::move(names)});

return *this;

}

inline CommandCatalogue &addArguments(std::string group, std::vector<std::string> names) {

_arguments.push_back({std::move(group), std::move(names)});

return *this;

}

inline const std::vector<Group> &commandGroups() const {

return _commands;

}

inline const std::vector<Group> &optionGroups() const {

return _options;

}

inline const std::vector<Group> &argumentGroups() const {

return _arguments;

}

inline bool isEmpty() const {

return _commands.empty() && _options.empty() && _arguments.empty();

}

private:

std::vector<Group> _commands;

std::vector<Group> _options;

std::vector<Group> _arguments;

public:

/// What to run once this command is the one that was named. Its return value is the

/// program's.

using Handler = std::function<int(const ParseResult &)>;

Command() = default;

inline Command(std::string name, std::string desc = {})

: _name(std::move(name)), _desc(std::move(desc)) {

}

inline Command &addArgument(Argument argument) {

_args.emplace_back(std::move(argument));

return *this;

}

inline Command &addArguments(std::vector<Argument> arguments) {

for (auto &item : arguments) {

addArgument(std::move(item));

}

return *this;

}

inline Command &addOption(Option option) {

_options.emplace_back(std::move(option));

return *this;

}

inline Command &addOptions(std::vector<Option> options) {

for (auto &item : options) {

addOption(std::move(item));

}

return *this;

}

inline Command &addCommand(Command command) {

_commands.emplace_back(std::move(command));

return *this;

}

inline Command &addCommands(std::vector<Command> commands) {

for (auto &item : commands) {

addCommand(std::move(item));

}

return *this;

}

inline Command &setHandler(Handler handler) {

_handler = std::move(handler);

return *this;

}

inline Command &setCatalogue(CommandCatalogue catalogue) {

_catalogue = std::move(catalogue);

return *this;

}

/// What a Version option prints.

inline Command &setVersion(std::string version) {

_version = std::move(version);

return *this;

}

/// The version option, with the level that lets it be answered on a command line that is

/// otherwise missing everything it needs.

///

/// The switch is this command's and the string cascades, so a subcommand adds its own

/// switch and says a version of its own or does not. An empty \a version is the second

/// of those: the switch answers here with whatever the nearest command above it said.

/// Where the whole path is empty, invoke() leaves the Version role for the handler.

/// \sa ParseResult::versionText()

///

/// \code

/// root.addVersionOption("1.0");

/// root.findCommand("sub")->addVersionOption(""); // prog sub --version prints 1.0

/// \endcode

inline Command &addVersionOption(std::string version, std::vector<std::string> tokens = {},

std::string desc = {}) {

_version = std::move(version);

return addOption(Option(Option::Version, std::move(tokens), std::move(desc))

.prior(Option::IgnoreMissingSymbols));

}

/// The help option, likewise.

///

/// \param showIfNoArguments Answer a command line with nothing on it at all, so that a

/// bare program name prints its help.

/// \param recursive Keep it in scope for the subcommands as well.

/// \param tokens The spellings, or the usual ones when empty.

/// \param desc The description, or the usual one when empty.

inline Command &addHelpOption(bool showIfNoArguments = false, bool recursive = false,

std::vector<std::string> tokens = {}, std::string desc = {}) {

return addOption(Option(Option::Help, std::move(tokens), std::move(desc))

.prior(showIfNoArguments ? Option::AutoSetWhenNoSymbols

: Option::IgnoreMissingSymbols)

.recursive(recursive));

}

inline Command &setDescription(std::string desc) {

_desc = std::move(desc);

return *this;

}

inline const std::string &name() const {

return _name;

}

inline const std::string &description() const {

return _desc;

}

inline const std::string &version() const {

return _version;

}

inline const std::vector<Argument> &arguments() const {

return _args;

}

inline const std::vector<Option> &options() const {

return _options;

}

inline const std::vector<Command> &commands() const {

return _commands;

}

inline const Handler &handler() const {

return _handler;

}

inline const CommandCatalogue &catalogue() const {

return _catalogue;

}

/// The subcommand named \a name, or null. Only one level down.

inline const Command *findCommand(std::string_view name) const {

for (const auto &item : _commands) {

if (item._name == name) {

return &item;

}

}

return nullptr;

}

/// The option answering to \a token, or null. A token is any of an option's spellings,

/// not only the first.

inline const Option *findOption(std::string_view token) const {

for (const auto &item : _options) {

for (const auto &spelling : item.tokens()) {

if (spelling == token) {

return &item;

}

}

}

return nullptr;

}

private:

std::string _name;

std::string _desc;

std::string _version;

std::vector<Argument> _args;

std::vector<Option> _options;

std::vector<Command> _commands;

Handler _handler;

CommandCatalogue _catalogue;