OctaForge
/
libostd
1
0
Fork 1
Code Issues Pull Requests Releases Wiki Activity
libostd/ostd/argparse.hh

1915 lines
62 KiB
C++
Raw Permalink Blame History

/** @addtogroup Utilities
* @{
*/
/** @file argparse.hh
*
* @brief Portable argument parsing.
*
* Provides a powerful argument parser that can handle a wide variety of
* cases, including POSIX and GNU argument ordering, different argument
* formats, optional values and type conversions.
*
* @include argparse.cc
*
* @copyright See COPYING.md in the project tree for further information.
*/
#ifndef OSTD_ARGPARSE_HH
#define OSTD_ARGPARSE_HH
#include <cstdio>
#include <cctype>
#include <algorithm>
#include <optional>
#include <vector>
#include <memory>
#include <stdexcept>
#include <utility>
#include <functional>
#include <type_traits>
#include <ostd/algorithm.hh>
#include <ostd/format.hh>
#include <ostd/string.hh>
#include <ostd/io.hh>
namespace ostd {
/** @addtogroup Utilities
* @{
*/
/** @brief The error thrown on parsing and other failures. */
struct OSTD_EXPORT arg_error: std::runtime_error {
using std::runtime_error::runtime_error;
/* empty, for vtable placement */
virtual ~arg_error();
template<typename ...A>
arg_error(string_range fmt, A const &...args):
arg_error(format(appender<std::string>(), fmt, args...).get())
{}
};
/** @brief A contiguous range type used for argument values.
*
* This range type has immutable contents and doesn't own its memory. It
* is represented as a regular string slice with the appropraite character
* and traits types. The `T` template type is a character type, usually
* a `char` but can be `wchar_t`, `char16_t`, `char32_t` as well.
*/
template<typename T>
using arg_value_type = basic_char_range<T const>;
/** @brief The range type passed to argument action callbacks.
*
* It's a contiguous range of `const` ostd::arg_value_type.
*/
template<typename T>
using arg_value_range = iterator_range<arg_value_type<T> const *>;
/** @brief The type of an argument class. */
enum class arg_type {
OPTIONAL = 0, ///< An optional argument.
POSITIONAL, ///< A positional argument.
GROUP, ///< A group of arguments.
MUTUALLY_EXCLUSIVE_GROUP ///< A group of mutually exclusive optionals.
};
/** @brief Defines the value requirements of an argument.
*
* The value requirement is paired with an integer defining the actual
* number of values. This number is valid for `EXACTLY` (defining the
* actual number of values) and for `ALL` (defining the minimum number
* of values) but not for the other two.
*
* See ostd::basic_arg_parser for detailed behavior.
*/
enum class arg_value {
EXACTLY, ///< An exact number of arguments.
OPTIONAL, ///< A single optional argument.
ALL, ///< All arguments until an optional.
REST ///< The rest of the arguments.
};
/** @brief A base class for all argument types.
*
* This base class is abstract so it cannot be instantiated.
*/
struct OSTD_EXPORT arg_description {
friend struct arg_description_container;
friend struct arg_mutually_exclusive_group;
friend struct arg_group;
/** @brief The base class contains no data. */
virtual ~arg_description();
/** @brief Gets an ostd::arg_type for the class. */
virtual arg_type type() const noexcept = 0;
protected:
/** @brief Finds an argument within the argument including itself.
*
* Given a name and optionally a type, this finds an optional or
* a positional argument of the given name. If the argument itself
* matches the parameters, it may return itself. For groups, it
* will search in the group (recursively) until something is
* found. If nothing is found, `nullptr` is returned.
*
* The bool here indicates whether we're currently parsing.
*/
virtual arg_description *find_arg(
string_range, std::optional<arg_type>, bool
) {
return nullptr;
}
/** @brief Does nothing. */
arg_description() {}
};
/** @brief A base class for optional and positional arguments.
*
* Optionals and positionals derive from this but not groups. It implements
* things common for both positional and optional arguments, including
* handling of ostd::arg_value. help and metavars.
*
* It's not instantiated directly.
*/
struct OSTD_EXPORT arg_argument: arg_description {
/* empty, for vtable placement */
virtual ~arg_argument();
/** @brief Sets the help for the argument.
*
* The help string is stored internally. Returns itself.
*/
arg_argument &help(string_range str) {
p_helpstr = std::string{str};
return *this;
}
/** @brief Gets the help string set by help(). */
string_range help() const noexcept {
return p_helpstr;
}
/** @brief Sets the metavar for the argument.
*
* A metavar is a string displayed in help listing either in place
* of a value (for optionals) or as the argument name itself (for
* positionals). See ostd::default_help_formatter for more.
*/
arg_argument &metavar(string_range str) {
p_metavar = std::string{str};
return *this;
}
/** @brief Gets the metavar string set by metavar(). */
string_range metavar() const noexcept {
return p_metavar;
}
/** @brief Gets the value requirement for the argument */
arg_value needs_value() const noexcept {
return p_valreq;
}
/** @brief Gets the number of values for needs_value(). */
std::size_t nargs() const noexcept {
return p_nargs;
}
protected:
/** @brief A helper constructor with ostd::arg_value.
*
* This is called by ostd::arg_optional and ostd::arg_positional.
* This version specifies an explicit value requirement plus a
* number of arguments.
*/
arg_argument(arg_value req, std::size_t nargs):
arg_description(), p_nargs(nargs), p_valreq(req)
{}
/** @brief A helper constructor with a number of arguments.
*
* The ostd::arg_value requirement is always `EXACTLY`.
*/
arg_argument(std::size_t nargs):
arg_description(),
p_nargs(nargs),
p_valreq(arg_value::EXACTLY)
{}
private:
std::string p_helpstr, p_metavar;
std::size_t p_nargs;
arg_value p_valreq;
};
/** @brief An optional argument class.
*
* An optional argument is composed of a prefix (frequently `-` or `--`,
* but can be anything allowed by the parser), a name and optionally a
* value or several values. Optional arguments are called optional because
* they don't have to be present. You can however limit how many times they
* can be used.
*
* An optional argument can have multiple names defining short and long
* arguments. Short arguments frequently have a format like `-a` while
* long ones often look like `--arg`. There is no restriction here as
* long as the name begins with at least one allowed prefix character,
* so arguments like `-arg` or `--a` or even `---x` are allowed.
*
*See ostd::basic_arg_parser for more.
*/
struct OSTD_EXPORT arg_optional: arg_argument {
template<typename HelpFormatter>
friend struct basic_arg_parser;
friend struct arg_description_container;
friend struct arg_group;
friend struct arg_mutually_exclusive_group;
/* empty, for vtable placement */
virtual ~arg_optional();
/** @brief Gets the argument class type (ostd::arg_type).
*
* The value is always `OPTIONAL`.
*/
arg_type type() const noexcept {
return arg_type::OPTIONAL;
}
/** @brief Gets how many times the argument has been specified. */
std::size_t used() const noexcept {
return p_used;
}
/** @brief Sets the action to run when the argument is used.
*
* The function is called with a finite random access range
* of ostd::string_range, each containing a value. It's not
* expected to return anything.
*/
template<typename F>
arg_optional &action(F func) {
p_action = func;
return *this;
}
/** @brief Like ostd::arg_argument::help(). */
arg_optional &help(string_range str) {
arg_argument::help(str);
return *this;
}
/** @brief Gets the metavar string set by help(). */
string_range help() const noexcept {
return arg_argument::help();
}
/** @brief Like ostd::arg_argument::metavar(). */
arg_optional &metavar(string_range str) {
arg_argument::metavar(str);
return *this;
}
/** @brief Gets the metavar string set by metavar(). */
string_range metavar() const noexcept {
return arg_argument::metavar();
}
/** @brief Gets the actual metavar used in help listing.
*
* Unlike just metavar(), it accounts for the case when the
* provided metavar is empty, falling back to transforming
* a suitable argument name into one.
*/
std::string real_metavar() const {
std::string mt{metavar()};
if (mt.empty()) {
string_range fb = longest_name();
if (!fb.empty()) {
char pfx = fb[0];
while (!fb.empty() && (fb.front() == pfx)) {
fb.pop_front();
}
}
if (fb.empty()) {
mt = "VALUE";
} else {
mt.append(fb.data(), fb.size());
std::transform(mt.begin(), mt.end(), mt.begin(), toupper);
}
}
return mt;
}
/** @brief Sets the limit on how many times this can be used.
*
* By default there is no limit (the value is 0). You can use this
* to restrict this to for example 1 use. The parsing will then
* throw ostd::arg_error if it's used more.
*/
arg_optional &limit(std::size_t n) noexcept {
p_limit = n;
return *this;
}
/** @brief Adds an extra optional name.
*
* Using the constructor, you can add 1 or 2 names. If you want
* this argument to be accessible with more names, you use this.
*/
arg_optional &add_name(string_range name) {
p_names.emplace_back(name);
return *this;
}
/** @brief Gets a read-only finite random access range of names.
*
* The value type of this range is an `std::string const`.
*/
auto names() const noexcept {
return iter(p_names);
}
/** @brief Gets the longest name this option can be referred to by.
*
* This is used in error messages and fallback metavar in help listing.
*/
string_range longest_name() const noexcept {
string_range ret;
for (auto &s: p_names) {
if (s.size() > ret.size()) {
ret = s;
}
}
return ret;
}
/** @brief Checks if the optional argument must be specified.
*
* In vast majority of cases, optional arguments are optional.
*/
bool required() const noexcept {
return p_required;
}
protected:
arg_optional() = delete;
/** @brief Constructs the optional argument.
*
* See arg_description_container::add_optional().
*/
arg_optional(arg_value req, std::size_t nargs, bool required):
arg_argument(req, nargs), p_required(required)
{
validate_req(req);
}
/** @brief Constructs the optional argument.
*
* See arg_description_container::add_optional(). The ostd::arg_value
* requirement is `EXACTLY` here.
*/
arg_optional(std::size_t nargs, bool required):
arg_argument(nargs), p_required(required)
{}
/** @brief See arg_description::find_arg().
*
* If `tp` is given, it will be checked. All names are iterated
* and compared against `name`. If any matches, `this` will be
* returned. Otherwise `nullptr` will be returned.
*/
arg_description *find_arg(
string_range name, std::optional<arg_type> tp, bool
) {
if (tp && (*tp != type())) {
return nullptr;
}
for (auto const &nm: p_names) {
if (name == nm) {
return this;
}
}
return nullptr;
}
/** @brief Marks the argument as used.
*
* If the number of uses is limited and the limit has already been
* reached, ostd::arg_error is thrown. Otherwise, the usage counter
* is incremented and if an action has been set, it's called with
* the given range of values. How many values the range contains
* depends on the value requirement of the argument, so it can
* be anything - empty, a single value or several.
*
* The action can throw, it's not caught and gets propagated all
* the way to the outside.
*/
void set_values(string_range argname, arg_value_range<char> vals) {
if (p_limit && (p_used == p_limit)) {
throw arg_error{
"argument '%s' can be used at most %d times", argname, p_limit
};
}
++p_used;
if (p_action) {
p_action(vals);
}
}
/** @brief Resets the usage counter. */
void reset() {
p_used = 0;
}
private:
void validate_req(arg_value req) const {
switch (req) {
case arg_value::EXACTLY:
case arg_value::OPTIONAL:
case arg_value::ALL:
break;
case arg_value::REST:
throw arg_error{"invalid argument requirement"};
}
}
std::function<void(arg_value_range<char>)> p_action;
std::vector<std::string> p_names;
std::size_t p_used = 0, p_limit = 0;
bool p_required;
};
/** @brief A positional argument class.
*
* A positional argument is not prefixed. It also doesn't have to always
* be used, so positional arguments with optional values are possible.
* The important part is that positional arguments have a strictly
* defined order and don't have a specific format. They simply capture
* values in the list that are in their positions. Also, obviously they
* are only used once so their usage is a boolean, not a counter.
*
*See ostd::basic_arg_parser for more.
*/
struct OSTD_EXPORT arg_positional: arg_argument {
template<typename HelpFormatter>
friend struct basic_arg_parser;
friend struct arg_description_container;
/* empty, for vtable placement */
virtual ~arg_positional();
/** @brief Gets the argument class type (ostd::arg_type).
*
* The value is always `POSITIONAL`.
*/
arg_type type() const noexcept {
return arg_type::POSITIONAL;
}
/** @brief Gets the name of the positional argument.
*
* A name is just a unique label. It's also used in place
* of metavar() when no metavar is explicitly set.
*/
string_range name() const noexcept {
return p_name;
}
/** @brief Sets the action to run when the argument is used.
*
* The function is called with a finite random access range
* of ostd::string_range, each containing a value. It's not
* expected to return anything.
*/
template<typename F>
arg_positional &action(F func) {
p_action = func;
return *this;
}
/** @brief Like ostd::arg_argument::help(). */
arg_positional &help(string_range str) {
arg_argument::help(str);
return *this;
}
/** @brief Gets the metavar string set by help(). */
string_range help() const noexcept {
return arg_argument::help();
}
/** @brief Like ostd::arg_argument::metavar(). */
arg_positional &metavar(string_range str) {
arg_argument::metavar(str);
return *this;
}
/** @brief Gets the metavar string set by metavar(). */
string_range metavar() const noexcept {
return arg_argument::metavar();
}
/** @brief Checks if the positional arg has been used.
*
* If the argument requirement is `EXACTLY` or if it's `ALL` with at
* least 1 argument, this will always be true after parsing unless
* an error happens. In other cases it can be false.
*/
bool used() const noexcept {
return p_used;
}
/** @brief Resets the usage flag. */
void reset() {
p_used = false;
}
protected:
arg_positional() = delete;
/** @brief Constructs the positional argument.
*
* See arg_description_container::add_positional().
*/
arg_positional(string_range name, arg_value req, std::size_t nargs):
arg_argument(req, nargs),
p_name(name)
{}
/** @brief Constructs the positional argument.
*
* See arg_description_container::add_positional(). The ostd::arg_value
* requirement is `EXACTLY` here.
*/
arg_positional(string_range name, std::size_t nargs):
arg_argument(nargs),
p_name(name)
{}
/** @brief See arg_description::find_arg().
*
* If `tp` is given, it will be checked. The given name is checked
* against the argument's name. Then it will appropriately return
* either `this` or `nullptr`.
*/
arg_description *find_arg(
string_range name, std::optional<arg_type> tp, bool
) {
if ((tp && (*tp != type())) || (name != ostd::citer(p_name))) {
return nullptr;
}
return this;
}
/** @brief Marks the argument as used.
*
* The used flag is set and if an action has been set, it's called
* with the given range of values. How many values the range contains
* depends on the value requirement of the argument, so it can be
* anything - empty, a single value or several.
*
* The action can throw, it's not caught and gets propagated all
* the way to the outside.
*/
void set_values(arg_value_range<char> vals) {
p_used = true;
if (p_action) {
p_action(vals);
}
}
private:
std::function<void(arg_value_range<char>)> p_action;
std::string p_name;
bool p_used = false;
};
/** @brief A group of mutually exclusive optional arguments.
*
* This is a group of optional arguments that cannot be used together.
* Mutually exclusive groups allow all of their arguments to be used,
* but if more than one is used, an ostd::arg_error is thrown and
* parsing is aborted.
*
* A mutually exclusive group can also have the `required` flag set
* in which case one of the arguments must always be used.
*/
struct OSTD_EXPORT arg_mutually_exclusive_group: arg_description {
friend struct arg_description_container;
/* empty, for vtable placement */
virtual ~arg_mutually_exclusive_group();
/** @brief Gets the argument class type (ostd::arg_type).
*
* The value is always `MUTUALLY_EXCLUSIVE_GROUP`.
*/
arg_type type() const noexcept {
return arg_type::MUTUALLY_EXCLUSIVE_GROUP;
}
/** @brief Adds an optional argument with one name.
*
* See ostd::arg_description_container::add_optional(). The
* only difference is that "required" arguments are not allowed,
* so that will always be `false` and cannot be specified.
*/
arg_optional &add_optional(
string_range name, arg_value req, std::size_t nargs = 1
) {
auto &ret = add_member<arg_optional>(req, nargs, false);
ret.add_name(name);
return ret;
}
/** @brief Adds an optional argument with one name.
*
* See ostd::arg_description_container::add_optional(). The
* only difference is that "required" arguments are not allowed,
* so that will always be `false` and cannot be specified.
*/
arg_optional &add_optional(string_range name, std::size_t nargs) {
auto &ret = add_member<arg_optional>(nargs, false);
ret.add_name(name);
return ret;
}
/** @brief Adds an optional argument with two names.
*
* See ostd::arg_description_container::add_optional(). The
* only difference is that "required" arguments are not allowed,
* so that will always be `false` and cannot be specified.
*/
arg_optional &add_optional(
string_range name1, string_range name2, arg_value req,
std::size_t nargs = 1
) {
auto &ret = add_member<arg_optional>(req, nargs, false);
ret.add_name(name1);
ret.add_name(name2);
return ret;
}
/** @brief Adds an optional argument with two names.
*
* See ostd::arg_description_container::add_optional(). The
* only difference is that "required" arguments are not allowed,
* so that will always be `false` and cannot be specified.
*/
arg_optional &add_optional(
string_range name1, string_range name2, std::size_t nargs
) {
auto &ret = add_member<arg_optional>(nargs, false);
ret.add_name(name1);
ret.add_name(name2);
return ret;
}
/** @brief Calls `func` for each argument in the group.
*
* The function takes a reference to ostd::arg_description `const`.
* It returns `true` if it's meant to continue or `false` if the
* loop should be aborted.
*
* This function returns `false` if the loop was aborted and `true`
* if it finished successfully.
*/
template<typename F>
bool for_each(F &&func) const {
for (auto &desc: p_opts) {
if (!func(*desc)) {
return false;
}
}
return true;
}
/** Checks if at least one argument must be used. */
bool required() const noexcept {
return p_required;
}
protected:
/** @brief Initializes the group. */
arg_mutually_exclusive_group(bool required = false):
p_required(required)
{}
/** @brief See arg_description::find_arg().
*
* This iterates over its optional arguments and calls their
* own `find_arg()` on each, returning the first matching
* result. However, if `parsing` is set, it will also check
* whether any has been used and if one was and it isn't the
* one that was matched, it throws ostd::arg_error with the
* appropriate error message. That's how the mutual exclusion
* is dealt with.
*/
arg_description *find_arg(
string_range name, std::optional<arg_type> tp, bool parsing
) {
string_range used;
for (auto &opt: p_opts) {
if (auto *p = opt->find_arg(name, tp, parsing); p) {
if (parsing && !used.empty()) {
throw arg_error{
"argument '%s' not allowed with argument '%s'",
name, used
};
}
return p;
}
used = static_cast<arg_optional &>(*opt).longest_name();
}
return nullptr;
}
/** @brief See arg_description_container::add_member(). */
template<typename T, typename ...A>
T &add_member(A &&...args) {
auto *ap = new T(std::forward<A>(args)...);
std::unique_ptr<arg_description> p{ap};
p_opts.push_back(std::move(p));
return *ap;
}
private:
std::vector<std::unique_ptr<arg_description>> p_opts;
bool p_required;
};
/** @brief A container for arguments and groups.
*
* Used as a base for ostd::arg_group as well as ostd::basic_arg_parser.
* It defines common methods for them as well as insertion calls. There
* is no insertion call for regular argument groups though as those
* may only be inserted from a parser.
*/
struct arg_description_container {
/** @brief Adds an optional argument with one name.
*
* This version takes an explicit value requirement, see the
* appropriate constructors of ostd::arg_argument. The value
* requirement can be `EXACTLY`, `OPTIONAL` or `ALL` but never
* `REST`. If it's not one of the allowed ones, ostd::arg_error
* is thrown.
*
* The `required` argument specifies whether this optional
* argument must be specified. In most cases optional
* arguments are optional, but not always.
*/
arg_optional &add_optional(
string_range name, arg_value req,
std::size_t nargs = 1, bool required = false
) {
auto &ret = add_member<arg_optional>(req, nargs, required);
ret.add_name(name);
return ret;
}
/** @brief Adds an optional argument with one name.
*
* This version takes only a number, see the appropriate
* constructors of ostd::arg_argument.
*
* The `required` argument specifies whether this optional
* argument must be specified. In most cases optional
* arguments are optional, but not always.
*/
arg_optional &add_optional(
string_range name, std::size_t nargs, bool required = false
) {
auto &ret = add_member<arg_optional>(nargs, required);
ret.add_name(name);
return ret;
}
/** @brief Adds an optional argument with two names.
*
* The typical combination is a short and a long name.
*
* This version takes an explicit value requirement, see the
* appropriate constructors of ostd::arg_argument. The value
* requirement can be `EXACTLY`, `OPTIONAL` or `ALL` but never
* `REST`. If it's not one of the allowed ones, ostd::arg_error
* is thrown.
*
* The `required` argument specifies whether this optional
* argument must be specified. In most cases optional
* arguments are optional, but not always.
*/
arg_optional &add_optional(
string_range name1, string_range name2, arg_value req,
std::size_t nargs = 1, bool required = false
) {
auto &ret = add_member<arg_optional>(req, nargs, required);
ret.add_name(name1);
ret.add_name(name2);
return ret;
}
/** @brief Adds an optional argument with two names.
*
* The typical combination is a short and a long name.
*
* This version takes only a number, see the appropriate
* constructors of ostd::arg_argument.
*
* The `required` argument specifies whether this optional
* argument must be specified. In most cases optional
* arguments are optional, but not always.
*/
arg_optional &add_optional(
string_range name1, string_range name2,
std::size_t nargs, bool required = false
) {
auto &ret = add_member<arg_optional>(nargs, required);
ret.add_name(name1);
ret.add_name(name2);
return ret;
}
/** @brief Adds a positional argument.
*
* This version takes an explicit value requirement,
* see the appropriate constructors of ostd::arg_argument.
*/
arg_positional &add_positional(
string_range name, arg_value req = arg_value::EXACTLY,
std::size_t nargs = 1
) {
return add_member<arg_positional>(name, req, nargs);
}
/** @brief Adds a positional argument.
*
* This version takes only a number, see the appropriate
* constructors of ostd::arg_argument.
*/
arg_positional &add_positional(string_range name, std::size_t nargs) {
return add_member<arg_positional>(name, nargs);
}
/** @brief Adds a mutually exclusive group. */
template<typename ...A>
arg_mutually_exclusive_group &add_mutually_exclusive_group(
bool required = false
) {
return add_member<arg_mutually_exclusive_group>(required);
}
/** @brief Calls `func` for each argument in the container.
*
* The iteration is optionally recursive. It goes through mutually
* exclusive groups when `iter_ex` is true and also through normal
* groups if `iter_grp` is true.
*
* The function takes a reference to ostd::arg_description `const`.
* It returns `true` if it's meant to continue or `false` if the
* loop should be aborted.
*
* This function returns `false` if the loop was aborted and `true`
* if it finished successfully.
*/
template<typename F>
bool for_each(F &&func, bool iter_ex, bool iter_grp) const;
protected:
/** @brief Initializes the data. */
arg_description_container() {}
/** @brief Finds an argument in the container.
*
* Iterates through everything, calling their own `find_arg()`
* on each (see arg_description::find_arg()). If that returns
* something valid, it's dynamically cast to a pointer to `AT`
* and if that is still valid, it's dereferenced and returned.
* Otherwise it goes on to the next one.
*
* If nothing is found, ostd::arg_error is thrown with the
* appropriate error message.
*/
template<typename AT>
AT &find_arg(string_range name, bool parsing) {
for (auto &p: p_opts) {
auto *pp = p->find_arg(name, std::nullopt, parsing);
if (!pp) {
continue;
}
if (auto *r = dynamic_cast<AT *>(pp); r) {
return *r;
}
break;
}
throw arg_error{"unknown argument '%s'", name};
}
/** @brief Adds a member in the container.
*
* The `T` is the type to add, inherited from ostd::arg_description.
* The arguments are forwarded to the constructor. It also makes sure
* that when something throws, no resources are leaked.
*/
template<typename T, typename ...A>
T &add_member(A &&...args) {
auto *ap = new T(std::forward<A>(args)...);
std::unique_ptr<arg_description> p{ap};
p_opts.push_back(std::move(p));
return *ap;
}
std::vector<std::unique_ptr<arg_description>> p_opts;
};
/** @brief A group of arguments.
*
* The arguments in the group can be whatever can be inserted into
* an ostd::arg_description_container. Actual argument groups show
* in help listing separately from each other and from general args.
*
* A group is named and can optionally have a title. The title is
* displayed in help listing. If not set, the name is displayed.
*/
struct OSTD_EXPORT arg_group: arg_description, arg_description_container {
friend struct arg_description_container;
/* empty, for vtable placement */
virtual ~arg_group();
/** @brief Gets the argument class type (ostd::arg_type).
*
* The value is always `GROUP`.
*/
arg_type type() const noexcept {
return arg_type::GROUP;
}
/** @brief Gets the name of the group. */
string_range name() const noexcept {
return p_name;
}
/** @brief Gets the title of the group.
*
* If title was not set properly, it's like name().
*/
string_range title() const noexcept {
if (p_title.empty()) {
return p_name;
}
return p_title;
}
protected:
arg_group() = delete;
/** @brief Constructs the group. See basic_arg_parser::add_group(). */
arg_group(string_range name, string_range title = string_range{}):
arg_description(), arg_description_container(),
p_name(name), p_title(title)
{}
/** @brief See arg_description::find_arg().
*
* This iterates over its arguments and calls their own `find_arg()`
* on each, returning the first matching result or `nullptr`.
*/
arg_description *find_arg(
string_range name, std::optional<arg_type> tp, bool parsing
) {
for (auto &opt: p_opts) {
if (auto *p = opt->find_arg(name, tp, parsing); p) {
return p;
}
}
return nullptr;
}
private:
std::string p_name, p_title;
};
template<typename F>
inline bool arg_description_container::for_each(
F &&func, bool iter_ex, bool iter_grp
) const {
std::remove_reference_t<F> &fref = func;
for (auto &desc: p_opts) {
switch (desc->type()) {
case arg_type::OPTIONAL:
case arg_type::POSITIONAL:
if (!fref(*desc)) {
return false;
}
break;
case arg_type::GROUP:
if (!iter_grp) {
if (!fref(*desc)) {
return false;
}
continue;
}
if (!static_cast<arg_group const &>(*desc).for_each(
fref, iter_ex, iter_grp
)) {
return false;
}
break;
case arg_type::MUTUALLY_EXCLUSIVE_GROUP:
if (!iter_ex) {
if (!fref(*desc)) {
return false;
}
continue;
}
if (!static_cast<arg_mutually_exclusive_group const &>(
*desc
).for_each(fref)) {
return false;
}
break;
}
}
return true;
}
/** @brief A command line argument parser.
*
* This implements a universal parser for command line arguments.
*
* It supports positional arguments, optional arguments, groups and mutually
* exclusive groups. It supports GNU and POSIX style argument ordering. Help
* formatting is provided using `HelpFormatter`.
*
* Optional arguments with arbitrary prefixes constrained by a constructor
* string are supported. By default, the only allowed prefix character is
* the `-` character as in POSIX style arguments.
*
* The system also supports a special argument that will be skipped but will
* indicate that all following arguments after it are positional. By default
* this is a string of two instances of the first allowed prefix character,
* therefore `--` by default.
*
* GNU style argument ordering (default) means that optional and positional
* arguments can be mixed. POSIX style argument ordering means that optional
* arguments come first and when a non-optional argument is encountered, any
* argument after that is considered positional no matter the prefix.
*
* Generally, the input command line arguments are like this:
*
* ~~~
* --opt1 --opt2 --opt3 pos1 pos2 pos3
* ~~~
*
* With mixed mode, you can do something like:
*
* ~~~
* --opt1 pos1 --opt2 pos2 --opt3 pos3
* ~~~
*
* Using the special argument you can do this:
*
* ~~~
* --opt1 pos1 -- --pos2 --pos3
* ~~~
*
* With POSIX style:
*
* ~~~
* --opt1 pos1 --pos2 --pos3
* ~~~
*
* Optional arguments are formatted like this:
*
* ~~~
* --opt-with-no-value --opt-with-value=VALUE --opt-with-value VALUE
* ~~~
*
* Keep in mind that if you use the version with a space, you have an
* argument that requires a value and that is followed by an argument
* detected as optional (i.e. having at least one optional prefix char),
* it will not be assuemd to be the value and you will get an error
* (the parser will throw ostd::arg_error with an appropriate message).
*
* ~~~
* # errors
* --arg-with-value --foo
* # passes
* --arg-with-value=--foo
* ~~~
*
* The reason for this is to avoid potential mistakes.
*
* If an argument optionally takes a value and is followed by a value that
* does not have an optional-like format, it will be used as the value.
* If the `=` style value assignment is used, it will be assigned to the
* argument no matter the value's format. If it's followed by a value
* that looks like an optional, the argument will have no value and the
* following value will be assumed to be another argument.
*
* If an argument takes multiple values, the following can be done:
*
* ~~~
* --arg val1 val2 val3 ...
* --arg=val1 val2 val3 ...
* ~~~
*
* The `REST` value of ostd::arg_value is useful when coupled with a
* positional argument. First, all positional arguments preceding the
* one with `REST` are filled and then every single value no matter the
* format following the last non-`REST` positional value is used for
* the `REST` argument. If there is no non-`REST` positional argument
* before the `REST` one, the first non-optional argument onwards will
* be used for the `REST` argument. This is also true with GNU style
* mixed argument ordering.
*
* ~~~
* # multiple positionals followed by REST
* --foo pos1 pos2 [--part-of-rest part_of_rest --also-part-of-rest]
* # only REST
* --foo [part_of_rest --also-part-of-rest]
* ~~~
*
* The parser also makes no distinction between short and long arguments,
* the only requiremnt is at least one prefix character. Thus you can have
* arguments like `-arg`, `--arg`, `-a`, `--a` and their value-taking
* syntax is identical. If you define extra prefix characaters, you can
* also have syntax like `/arg` (DOS/Windows-style) or `++arg` or anything.
*
* The `progname` is used for help formatting. It's passed in during
* construction, but if you don't and you use the parse() call with
* `argc` and `argv` rather than range, `argv[0]] will be assumed to
* be the progname if not already set.
*/
template<typename HelpFormatter>
struct basic_arg_parser: arg_description_container {
private:
struct parse_stop {};
public:
/** @brief Constructs the parser.
*
* The `progname` argument is used for help listing. If empty, it
* can also be filled using parse() with `argc`/`argv`. The range
* based parse() will not set it and a fallback will be used.
*
* The `pfx_chars` argument defines allowed characters for optional
* argument prefixes. By default, only `-` is allowed.
*
* When `pos_sep` is not empty, it's the special argument that makes
* all following values to be positional. When empty, it's set to
* two instances of the first `pfx_chars` character, i.e. `--` by
* default.
*
* When `pfx_chars` does not contain at least one character,
* ostd::arg_error is thrown with the appropriate error.
*
* The `posix` argument enforces POSIX style argument ordering.
*/
basic_arg_parser(
string_range progname = string_range{},
string_range pfx_chars = "-",
string_range pos_sep = string_range{},
bool posix = false
):
arg_description_container(), p_progname(progname),
p_pfx_chars(pfx_chars), p_pos_sep(), p_posix(posix)
{
if (pfx_chars.empty()) {
throw arg_error{"at least one prefix character needed"};
}
if (pos_sep.empty()) {
p_pos_sep.append(2, pfx_chars[0]);
} else {
p_pos_sep.append(pos_sep.data(), pos_sep.size());
}
}
/** @brief Adds a group in the container.
*
* Groups require a name and optionally a title for help formatting.
*/
template<typename ...A>
arg_group &add_group(string_range name, string_range title = string_range{}) {
return add_member<arg_group>(name, title);
}
/** @brief Parses arguments using `argc` and `argv`.
*
* This is a convenience function for usage with standard C++ `main`.
* If `progname` was empty during construction, it's set from `argv[0]`.
* The arguments are `argv[1]` onwards.
*
* Otherwise the same as parse(InputRange).
*/
void parse(int argc, char **argv) {
if (p_progname.empty()) {
p_progname = argv[0];
}
parse(ostd::iter(&argv[1], &argv[argc]));
}
/** @brief Parses arguments.
*
* Parses arguments according to the rules. Actions are called where
* necessary and both positional and optional arguments are handled.
* If an error happens (action throws, mutually exclusive arguments
* are used or any other error condition), typically ostd::arg_error
* is thrown. The only times something else is thrown is when an
* action explicitly throws a different exception.
*/
template<typename InputRange>
void parse(InputRange args) {
/* count positional args until remainder */
std::size_t npos = 0;
bool has_rest = false;
for_each([&has_rest, &npos](auto const &arg) {
if (arg.type() == arg_type::OPTIONAL) {
const_cast<arg_optional &>(
static_cast<arg_optional const &>(arg)
).reset();
}
if (arg.type() != arg_type::POSITIONAL) {
return true;
}
auto const &desc = static_cast<arg_positional const &>(arg);
const_cast<arg_positional &>(desc).reset();
if (desc.needs_value() == arg_value::REST) {
has_rest = true;
return true;
}
if (!has_rest) {
++npos;
}
return true;
}, true, true);
bool allow_optional = true;
while (!args.empty()) {
string_range s{args.front()};
if (s == p_pos_sep) {
args.pop_front();
allow_optional = false;
continue;
}
if (allow_optional && is_optarg(s)) {
try {
parse_opt(s, args);
} catch (parse_stop) {
return;
}
continue;
}
if (p_posix) {
allow_optional = false;
}
try {
parse_pos(s, args, allow_optional);
} catch (parse_stop) {
return;
}
if (has_rest && npos) {
--npos;
if (!npos && !args.empty()) {
/* parse rest after all preceding positionals are filled
* if the only positional consumes rest, it will be filled
* by the above when the first non-optional is encountered
*/
try {
parse_pos(string_range{args.front()}, args, false);
} catch (parse_stop) {
return;
}
}
}
}
for_each([](auto const &arg) {
if (arg.type() == arg_type::MUTUALLY_EXCLUSIVE_GROUP) {
auto &mgrp = static_cast<
arg_mutually_exclusive_group const &
>(arg);
if (!mgrp.required()) {
return true;
}
std::vector<string_range> names;
bool cont = false;
mgrp.for_each([&names, &cont](auto const &marg) {
auto const &mopt = static_cast<arg_optional const &>(marg);
if (mopt.used()) {
cont = true;
return false;
}
names.push_back(mopt.longest_name());
return true;
});
if (!cont) {
throw arg_error{
"one of the arguments %('%s'%|, %) is required", names
};
}
return true;
}
if (arg.type() == arg_type::OPTIONAL) {
auto const &oarg = static_cast<arg_optional const &>(arg);
if (oarg.required() && !oarg.used()) {
throw arg_error{
"argument '%s' is required", oarg.longest_name()
};
}
return true;
}
auto const &desc = static_cast<arg_positional const &>(arg);
auto needs = desc.needs_value();
auto nargs = desc.nargs();
if ((needs != arg_value::EXACTLY) && (needs != arg_value::ALL)) {
return true;
}
if (!nargs || desc.used()) {
return true;
}
throw arg_error{"too few arguments"};
}, false, true);
}
/** @brief Formats help into the given output range.
*
* It does so using the help formatter. First `format_usage()`
* is called followed by `format_options()`. The range is then
* returned, forwarded.
*/
template<typename OutputRange>
OutputRange &&print_help(OutputRange &&range) {
p_helpfmt.format_usage(range);
p_helpfmt.format_options(range);
return std::forward<OutputRange>(range);
}
/** @brief A convenience print_help() with ostd::cout. */
void print_help() {
print_help(cout.iter());
}
/** @brief Gets an argument with the given name.
*
* It can be either optional or positional,
* ostd::arg_description_container::find_arg() is used
* in non-parsing mode.
*/
arg_argument &get(string_range name) {
return find_arg<arg_argument>(name, false);
}
/** @brief Gets the previously set progname. */
string_range progname() const noexcept {
return p_progname;
}
/** @brief Checks is POSIX style ordering is used. */
bool posix_ordering() const noexcept {
return p_posix;
}
/** @brief Sets if POSIX style ordering is used.
*
* The previous ordering style is returned.
*/
bool posix_ordering(bool v) noexcept {
return std::exchange(p_posix, v);
}
/** @brief When called within an action, aborts parsing.
*
* Do not call outside, as this throws an exception that is internal
* and cannot be handled. It's handled internally in the parser, so
* only use from actions if you want to stop the parsing. This is
* useful when e.g. doing help printing.
*/
void stop_parsing() {
throw parse_stop{};
}
private:
bool is_optarg(string_range arg) {
if (arg.size() <= 1) {
return false;
}
return (p_pfx_chars.find(arg[0]) != std::string::npos);
}
template<typename R>
void parse_opt(string_range argr, R &args) {
std::vector<std::string> vals;
if (auto sv = find(argr, '='); !sv.empty()) {
argr = argr.slice(0, argr.size() - sv.size());
sv.pop_front();
vals.emplace_back(sv);
}
args.pop_front();
std::string arg{argr};
auto &desc = find_arg<arg_optional>(arg, true);
auto needs = desc.needs_value();
auto nargs = desc.nargs();
/* optional argument takes no values */
if ((needs == arg_value::EXACTLY) && !nargs) {
/* value was provided through = */
if (!vals.empty()) {
throw arg_error{"argument '%s' takes no value", arg};
}
desc.set_values(arg, nullptr);
return;
}
if (
vals.empty() ||
(needs == arg_value::ALL) ||
((needs == arg_value::EXACTLY) && (nargs > 1))
) {
auto rargs = nargs;
if ((needs == arg_value::EXACTLY) && !vals.empty()) {
--rargs;
}
for (;;) {
bool pval = !args.empty() && !is_optarg(args.front());
if ((needs == arg_value::EXACTLY) && rargs && !pval) {
throw arg_error{
"argument '%s' needs exactly %d values",
arg, nargs
};
}
if (!pval || ((needs == arg_value::EXACTLY) && !rargs)) {
break;
}
vals.emplace_back(args.front());
args.pop_front();
if (rargs) {
--rargs;
}
}
}
if ((needs == arg_value::ALL) && (nargs > vals.size())) {
throw arg_error{
"argument '%s' needs at least %d values", arg, nargs
};
}
if (!vals.empty()) {
std::vector<string_range> srvals;
for (auto const &s: vals) {
srvals.push_back(s);
}
desc.set_values(
arg, ostd::iter(&srvals[0], &srvals[srvals.size()])
);
} else {
desc.set_values(arg, nullptr);
}
}
template<typename R>
void parse_pos(string_range argr, R &args, bool allow_opt) {
arg_positional *descp = nullptr;
for (auto &popt: p_opts) {
if (popt->type() != arg_type::POSITIONAL) {
continue;
}
arg_positional &o = *static_cast<arg_positional *>(popt.get());
if (o.used()) {
continue;
}
descp = &o;
break;
}
if (!descp) {
throw arg_error{"unexpected argument '%s'", argr};
}
arg_positional &desc = *descp;
auto needs = desc.needs_value();
auto nargs = desc.nargs();
std::vector<std::string> vals;
vals.emplace_back(argr);
args.pop_front();
if (needs == arg_value::REST) {
for (; !args.empty(); args.pop_front()) {
vals.emplace_back(args.front());
}
} else if (needs == arg_value::ALL) {
for (; !args.empty(); args.pop_front()) {
string_range v = args.front();
if (allow_opt && is_optarg(v)) {
break;
}
vals.emplace_back(v);
}
if (nargs > vals.size()) {
throw arg_error{
"positional argument '%s' needs at least %d values",
desc.name(), nargs
};
}
} else if ((needs == arg_value::EXACTLY) && (nargs > 1)) {
auto reqargs = nargs - 1;
while (reqargs) {
if (args.empty() || (allow_opt && is_optarg(args.front()))) {
throw arg_error{
"positional argument '%s' needs exactly %d values",
desc.name(), nargs
};
}
vals.emplace_back(args.front());
args.pop_front();
}
} /* else is OPTIONAL and we already have an arg */
std::vector<string_range> srvals;
for (auto const &s: vals) {
srvals.push_back(s);
}
desc.set_values(ostd::iter(&srvals[0], &srvals[srvals.size()]));
}
std::string p_progname, p_pfx_chars, p_pos_sep;
HelpFormatter p_helpfmt{*this};
bool p_posix = false;
};
/** @brief The default help formatter class for ostd::basic_arg_parser.
*
* It formats help with the following format:
*
* ~~~
* Usage: <progname> [opts] [args]
*
* Positional arguments:
* <metavar or name> <help string>
* <...> <help string>
*
* Optional arguments:
* -name1, --name2, ... <help string>
* -a ARG, --arg ARG <help string>
* -a [ARG] <help string>
* -a [ARG ...] <help string>
*
* Group title:
* <positional> <help string>
* <optional> <help string>
* ~~~
*
* See the respective methods for more details.
*/
struct default_help_formatter {
/** @brief Constructs the formatter with a parser. */
default_help_formatter(basic_arg_parser<default_help_formatter> &p):
p_parser(p)
{}
/** @brief Formats the usage line.
*
* If ostd::basic_arg_parser::progname() is empty, `program`
* is used as a fallback.
*/
template<typename OutputRange>
void format_usage(OutputRange &out) {
string_range progname = p_parser.progname();
if (progname.empty()) {
progname = "program";
}
format(out, "Usage: %s [opts] [args]\n", progname);
}
/** @brief Formats the options (after usage line).
*
* Positional arguments not belonging to any group are formatted
* first, with `\\nPositional arguments:\\n` header. Same goes with
* optional arguments, except with `\\nOptional arguments:\\n`.
*
* If either positional or optional arguments without group don't
* exist, the section is skipped.
*
* All arguments, in groups or not, are offset by 2 spaces. All
* help strings are aligned and offset by 2 spaces from the longest
* argument string.
*
* Group titles are formatted as `\\nTITLE:\\n`.
*
* Within groups, positional arguments come first and optional
* arguments second. Mutually exclusive groups are expanded.
* Actual arguments are formatted with format_option().
*/
template<typename OutputRange>
void format_options(OutputRange &out) {
std::size_t opt_namel = 0, pos_namel = 0, grp_namel = 0;
std::vector<arg_argument const *> allopt;
std::vector<arg_argument const *> allpos;
p_parser.for_each([
&allopt, &allpos, &opt_namel, &pos_namel, &grp_namel, this
](auto const &parg) {
auto cs = counting_sink(noop_sink<char>());
switch (parg.type()) {
case arg_type::OPTIONAL: {
auto &opt = static_cast<arg_optional const &>(parg);
this->format_option(cs, opt);
opt_namel = std::max(opt_namel, cs.get_written());
allopt.push_back(&opt);
break;
}
case arg_type::POSITIONAL: {
auto &opt = static_cast<arg_positional const &>(parg);
this->format_option(cs, opt);
pos_namel = std::max(pos_namel, cs.get_written());
allpos.push_back(&opt);
break;
}
case arg_type::GROUP:
static_cast<arg_group const &>(parg).for_each(
[&cs, &grp_namel, this](auto const &arg) {
auto ccs = cs;
this->format_option(ccs, arg);
grp_namel = std::max(grp_namel, ccs.get_written());
return true;
}, true, true
);
break;
case arg_type::MUTUALLY_EXCLUSIVE_GROUP:
static_cast<arg_mutually_exclusive_group const &>(
parg
).for_each(
[&cs, &opt_namel, &allopt, this](auto const &arg) {
auto ccs = cs;
this->format_option(ccs, arg);
opt_namel = std::max(opt_namel, ccs.get_written());
allopt.push_back(static_cast<
arg_optional const *
>(&arg));
return true;
}
);
break;
}
return true;
}, false, false);
std::size_t maxpad = std::max({opt_namel, pos_namel, grp_namel});
auto write_help = [&out, maxpad, this](
std::vector<arg_argument const *> const &args
) {
for (auto p: args) {
format(out, " ");
auto &parg = *p;
auto cr = counting_sink(out);
this->format_option(cr, parg);
out = std::move(cr.get_range());
auto help = parg.help();
if (help.empty()) {
out.put('\n');
} else {
std::size_t nd = maxpad - cr.get_written() + 2;
for (std::size_t i = 0; i < nd; ++i) {
out.put(' ');
}
format(out, "%s\n", help);
}
}
};
if (!allpos.empty()) {
format(out, "\nPositional arguments:\n");
write_help(allpos);
}
if (!allopt.empty()) {
format(out, "\nOptional arguments:\n");
write_help(allopt);
}
allopt.clear();
allpos.clear();
p_parser.for_each([
&write_help, &out, &allopt, &allpos
](auto const &arg) {
if (arg.type() != arg_type::GROUP) {
return true;
}
auto &garg = static_cast<arg_group const &>(arg);
format(out, "\n%s:\n", garg.title());
garg.for_each([&allopt, &allpos](auto const &marg) {
switch (marg.type()) {
case arg_type::OPTIONAL:
allopt.push_back(
static_cast<arg_optional const *>(&marg)
);
break;
case arg_type::POSITIONAL:
allpos.push_back(
static_cast<arg_positional const *>(&marg)
);
break;
case arg_type::GROUP:
case arg_type::MUTUALLY_EXCLUSIVE_GROUP:
/* should never happen */
throw arg_error{"invalid argument type"};
}
return true;
}, true, false);
write_help(allpos);
write_help(allopt);
return true;
}, false, false);
}
/** @brief Formats an optional argument.
*
* If a metavar exists (ostd::arg_optional::metavar()) then it's
* used as-is. Otherwise, the first name longer than 1 character
* without prefix is uppercased (without prefix) and used as a
* metavar. If thta fails, `VALUE` is used as a fallback.
*
* The option is formatted as `<name> <value>` for each name separated
* by a comma followed by a space. If the argument does not take any
* values, ` <value>` is not used. The format of `<value>` is the
* metavar when taking exactly one value, a space separated list
* of metavars when taking multiple, `[<metavar>]` with one optional
* value, `[<metavar> ...]` with all values with no "at least" count,
* and `<metavar> <metavar> [<metavar> ...]` for example when at least
* two values are necessary.
*/
template<typename OutputRange>
void format_option(OutputRange &out, arg_optional const &arg) {
std::string mt = arg.real_metavar();
auto names = arg.names();
for (;;) {
format(out, names.front());
switch (arg.needs_value()) {
case arg_value::EXACTLY: {
for (auto nargs = arg.nargs(); nargs; --nargs) {
format(out, " %s", mt);
}
break;
}
case arg_value::OPTIONAL:
format(out, " [%s]", mt);
break;
case arg_value::ALL:
for (auto nargs = arg.nargs(); nargs; --nargs) {
format(out, " %s", mt);
}
format(out, " [%s ...]", mt);
break;
case arg_value::REST:
break;
}
names.pop_front();
if (names.empty()) {
break;
}
format(out, ", ");
}
}
/** @brief Formats a positional argument.
*
* If a metavar exists (ostd::arg_positional::metavar()) then it's
* used as-is. Otherwise, the argument's name is used as-is.
*
* The argument is formatted simply as `<metavar>`.
*/
template<typename OutputRange>
void format_option(OutputRange &out, arg_positional const &arg) {
auto mt = arg.metavar();
if (mt.empty()) {
mt = arg.name();
}
format(out, mt);
}
/** @brief Formats either a positional or optional argument.
*
* The right call is decided according to arg_description::type().
* If it's neither, ostd::arg_error is thrown.
*/
template<typename OutputRange>
void format_option(OutputRange &out, arg_description const &arg) {
switch (arg.type()) {
case arg_type::OPTIONAL:
format_option(out, static_cast<arg_optional const &>(arg));
break;
case arg_type::POSITIONAL:
format_option(out, static_cast<arg_positional const &>(arg));
break;
case arg_type::GROUP:
case arg_type::MUTUALLY_EXCLUSIVE_GROUP:
/* should never happen */
throw arg_error{"invalid argument type"};
}
}
private:
basic_arg_parser<default_help_formatter> &p_parser;
};
/** @brief A default specialization of ostd::basic_arg_parser. */
using arg_parser = basic_arg_parser<default_help_formatter>;
/** @brief A help-printing argument action.
*
* When called with an output range and a reference to parser, this
* returns a function which can be passed as an argument action.
* The function prints help and aborts parsing, see
* ostd::arg_parser::stop_parsing().
*/
template<typename OutputRange>
inline auto arg_print_help(OutputRange o, arg_parser &p) {
return [o = std::move(o), &p](arg_value_range<char>) mutable {
p.print_help(o);
p.stop_parsing();
};
}
/** @brief Like ostd::arg_print_help() with ostd::cout. */
inline auto arg_print_help(arg_parser &p) {
return arg_print_help(cout.iter(), p);
}
/** @brief A constant-storing argument action.
*
* Given a value and a reference, this returns a function that copies
* the value into the reference using assignment. Use with arguments
* with no values from command line.
*/
template<typename T, typename U>
inline auto arg_store_const(T &&val, U &ref) {
return [val, &ref](arg_value_range<char>) mutable {
ref = std::move(val);
};
}
/** @brief A string-storing argument action.
*
* The returne function stores the first given value in the `ref`.
*/
template<typename T>
inline auto arg_store_str(T &ref) {
return [&ref](arg_value_range<char> r) mutable {
ref = T{r[0]};
};
}
/** @brief Like ostd::arg_store_const() with a `true` value. */
inline auto arg_store_true(bool &ref) {
return arg_store_const(true, ref);
}
/** @brief Like ostd::arg_store_const() with a `false` value. */
inline auto arg_store_false(bool &ref) {
return arg_store_const(false, ref);
}
/** @brief An unformatting argument action.
*
* The returned function takes the first value and unformats it
* into all the given references using a format string. For example
* if the given value is `5:10` and you want to unformat it into
* two integers, you use `%d:%d` as the format string.
*
* If the string cannot be unfortmatted exactly, an ostd::arg_error
* with an appropriate message is thrown.
*/
template<typename ...A>
inline auto arg_store_format(string_range fmt, A &...args) {
/* TODO: use ostd::format once it supports reading */
return [fmts = std::string{fmt}, argst = std::tie(args...)](
arg_value_range<char> r
) mutable {
std::apply([&fmts, istr = std::string{r[0]}](auto &...refs) {
if (sscanf(istr.data(), fmts.data(), &refs...) != sizeof...(A)) {
throw arg_error{
"argument requires format '%s' (got '%s')", fmts, istr
};
}
}, argst);
};
}
/** @} */
} /* namespace ostd */
#endif
/** @} */
Reference in New Issue View Git Blame Copy Permalink