/home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp

Returns the parser's full program name.

Returns the parser's full program name.- For top-level parsers, this is the same as the parser's name.

• For subparsers, the name is prefixed with its parent parser names.

Top-level parser: git Subparser: git submodule Nested subparser : git submodule init

// Copyright (c) 2023-2025 Jakub Musiał
// This file is part of the CPP-AP project (https://github.com/SpectraL519/cpp-ap).
// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include "argument.hpp"
#include "argument_group.hpp"
#include "detail/argument_token.hpp"
#include "types.hpp"
 
#include <algorithm>
#include <format>
#include <iostream>
#include <ranges>
#include <span>
 
#ifdef AP_TESTING
 
namespace ap_testing {
struct argument_parser_test_fixture;
} // namespace ap_testing
 
#endif
 
namespace ap {
 
class argument_parser;
 
enum class default_argument : std::uint8_t {
    p_input,
 
    p_output,
 
    o_help,
 
    o_version,
 
    o_input,
 
    o_output,
 
    o_multi_input,
 
    o_multi_output
};
 
enum class unknown_policy : std::uint8_t {
    fail, 
    warn, 
    ignore, 
    as_values 
};
 
namespace detail {
 
void add_default_argument(const default_argument, argument_parser&) noexcept;
 
} // namespace detail
 
class argument_parser {
public:
    argument_parser(const argument_parser&) = delete;
    argument_parser& operator=(const argument_parser&) = delete;
 
    argument_parser(argument_parser&&) = delete;
    argument_parser& operator=(argument_parser&&) = delete;
 
    argument_parser(const std::string_view name) : argument_parser(name, "") {}
 
    ~argument_parser() = default;
 
    argument_parser& program_version(const version& version) noexcept {
        this->_program_version.emplace(version.str());
        return *this;
    }
 
    argument_parser& program_version(std::string_view version) {
        if (util::contains_whitespaces(version))
            throw invalid_configuration("The program version cannot contain whitespace characters!"
            );
 
        this->_program_version.emplace(version);
        return *this;
    }
 
    argument_parser& program_description(std::string_view description) noexcept {
        this->_program_description.emplace(description);
        return *this;
    }
 
    argument_parser& verbose(const bool v = true) noexcept {
        this->_verbose = v;
        return *this;
    }
 
    argument_parser& unknown_arguments_policy(const unknown_policy policy) noexcept {
        this->_unknown_policy = policy;
        return *this;
    }
 
    template <util::c_range_of<default_argument> AR>
    argument_parser& default_arguments(const AR& arg_discriminators) noexcept {
        for (const auto arg_discriminator : arg_discriminators)
            detail::add_default_argument(arg_discriminator, *this);
        return *this;
    }
 
    argument_parser& default_arguments(
        const std::initializer_list<default_argument>& arg_discriminators
    ) noexcept {
        return this->default_arguments<>(arg_discriminators);
    }
 
    argument_parser& default_arguments(
        const std::same_as<default_argument> auto... arg_discriminators
    ) noexcept {
        (detail::add_default_argument(arg_discriminators, *this), ...);
        return *this;
    }
 
    template <util::c_argument_value_type T = std::string>
    positional_argument<T>& add_positional_argument(const std::string_view name) {
        return this->add_positional_argument<T>(this->_gr_positional_args, name);
    }
 
    template <util::c_argument_value_type T = std::string>
    positional_argument<T>& add_positional_argument(
        argument_group& group, const std::string_view name
    ) {
        this->_validate_group(group);
        this->_verify_arg_name_pattern(name);
 
        const detail::argument_name arg_name(std::make_optional<std::string>(name));
        if (this->_is_arg_name_used(arg_name))
            throw invalid_configuration::argument_name_used(arg_name);
 
        auto& new_arg_ptr =
            this->_positional_args.emplace_back(std::make_shared<positional_argument<T>>(arg_name));
        group._add_argument(new_arg_ptr);
        return static_cast<positional_argument<T>&>(*new_arg_ptr);
    }
 
    template <util::c_argument_value_type T = std::string>
    optional_argument<T>& add_optional_argument(
        const std::string_view name,
        const detail::argument_name_discriminator name_discr = n_primary
    ) {
        return this->add_optional_argument<T>(this->_gr_optional_args, name, name_discr);
    }
 
    template <util::c_argument_value_type T = std::string>
    optional_argument<T>& add_optional_argument(
        const std::string_view primary_name, const std::string_view secondary_name
    ) {
        return this->add_optional_argument<T>(
            this->_gr_optional_args, primary_name, secondary_name
        );
    }
 
    template <util::c_argument_value_type T = std::string>
    optional_argument<T>& add_optional_argument(
        argument_group& group,
        const std::string_view name,
        const detail::argument_name_discriminator name_discr = n_primary
    ) {
        this->_validate_group(group);
        this->_verify_arg_name_pattern(name);
 
        const auto arg_name =
            name_discr == n_primary
                ? detail::
                      argument_name{std::make_optional<std::string>(name), std::nullopt, this->_flag_prefix_char}
                : detail::argument_name{
                      std::nullopt, std::make_optional<std::string>(name), this->_flag_prefix_char
                  };
 
        if (this->_is_arg_name_used(arg_name))
            throw invalid_configuration::argument_name_used(arg_name);
 
        auto& new_arg_ptr =
            this->_optional_args.emplace_back(std::make_shared<optional_argument<T>>(arg_name));
        group._add_argument(new_arg_ptr);
        return static_cast<optional_argument<T>&>(*new_arg_ptr);
    }
 
    template <util::c_argument_value_type T = std::string>
    optional_argument<T>& add_optional_argument(
        argument_group& group,
        const std::string_view primary_name,
        const std::string_view secondary_name
    ) {
        this->_validate_group(group);
        this->_verify_arg_name_pattern(primary_name);
        this->_verify_arg_name_pattern(secondary_name);
 
        const detail::argument_name arg_name(
            std::make_optional<std::string>(primary_name),
            std::make_optional<std::string>(secondary_name),
            this->_flag_prefix_char
        );
        if (this->_is_arg_name_used(arg_name))
            throw invalid_configuration::argument_name_used(arg_name);
 
        auto& new_arg_ptr =
            this->_optional_args.emplace_back(std::make_shared<optional_argument<T>>(arg_name));
        group._add_argument(new_arg_ptr);
        return static_cast<optional_argument<T>&>(*new_arg_ptr);
    }
 
    template <bool StoreImplicitly = true>
    optional_argument<bool>& add_flag(
        const std::string_view name,
        const detail::argument_name_discriminator name_discr = n_primary
    ) {
        return this->add_optional_argument<bool>(name, name_discr)
            .default_values(not StoreImplicitly)
            .implicit_values(StoreImplicitly)
            .nargs(0ull);
    }
 
    template <bool StoreImplicitly = true>
    optional_argument<bool>& add_flag(
        const std::string_view primary_name, const std::string_view secondary_name
    ) {
        return this->add_optional_argument<bool>(primary_name, secondary_name)
            .default_values(not StoreImplicitly)
            .implicit_values(StoreImplicitly)
            .nargs(0ull);
    }
 
    template <bool StoreImplicitly = true>
    optional_argument<bool>& add_flag(
        argument_group& group,
        const std::string_view name,
        const detail::argument_name_discriminator name_discr = n_primary
    ) {
        return this->add_optional_argument<bool>(group, name, name_discr)
            .default_values(not StoreImplicitly)
            .implicit_values(StoreImplicitly)
            .nargs(0ull);
    }
 
    template <bool StoreImplicitly = true>
    optional_argument<bool>& add_flag(
        argument_group& group,
        const std::string_view primary_name,
        const std::string_view secondary_name
    ) {
        return this->add_optional_argument<bool>(group, primary_name, secondary_name)
            .default_values(not StoreImplicitly)
            .implicit_values(StoreImplicitly)
            .nargs(0ull);
    }
 
    argument_group& add_group(const std::string_view name) noexcept {
        return *this->_argument_groups.emplace_back(argument_group::create(*this, name));
    }
 
    argument_parser& add_subparser(const std::string_view name) {
        const auto subparser_it = std::ranges::find(
            this->_subparsers, name, [](const auto& subparser) { return subparser->_name; }
        );
        if (subparser_it != this->_subparsers.end())
            throw std::logic_error(std::format(
                "A subparser with the given name () already exists in parser '{}'",
                (*subparser_it)->_name,
                this->_program_name
            ));
 
        return *this->_subparsers.emplace_back(
            std::unique_ptr<argument_parser>(new argument_parser(name, this->_program_name))
        );
    }
 
    void parse_args(int argc, char* argv[]) {
        this->parse_args(std::span(argv + 1, static_cast<std::size_t>(argc - 1)));
    }
 
    template <util::c_forward_range_of<std::string, util::type_validator::convertible> AR>
    void parse_args(const AR& argv_rng) {
        parsing_state state(*this);
        this->_parse_args_impl(std::ranges::begin(argv_rng), std::ranges::end(argv_rng), state);
 
        if (not state.unknown_args.empty())
            throw parsing_failure(std::format(
                "Failed to deduce the argument for values [{}]", util::join(state.unknown_args)
            ));
    }
 
    void try_parse_args(int argc, char* argv[]) {
        this->try_parse_args(std::span(argv + 1, static_cast<std::size_t>(argc - 1)));
    }
 
    template <util::c_forward_range_of<std::string, util::type_validator::convertible> AR>
    void try_parse_args(const AR& argv_rng) {
        try {
            this->parse_args(argv_rng);
        }
        catch (const ap::argument_parser_exception& err) {
            std::cerr << "[ap::error] " << err.what() << std::endl
                      << this->resolved_parser() << std::endl;
            std::exit(EXIT_FAILURE);
        }
    }
 
    std::vector<std::string> parse_known_args(int argc, char* argv[]) {
        return this->parse_known_args(std::span(argv + 1, static_cast<std::size_t>(argc - 1)));
    }
 
    template <util::c_forward_range_of<std::string, util::type_validator::convertible> AR>
    std::vector<std::string> parse_known_args(const AR& argv_rng) {
        parsing_state state(*this, true);
        this->_parse_args_impl(std::ranges::begin(argv_rng), std::ranges::end(argv_rng), state);
        return std::move(state.unknown_args);
    }
 
    std::vector<std::string> try_parse_known_args(int argc, char* argv[]) {
        return this->try_parse_known_args(std::span(argv + 1, static_cast<std::size_t>(argc - 1)));
    }
 
    template <util::c_forward_range_of<std::string, util::type_validator::convertible> AR>
    std::vector<std::string> try_parse_known_args(const AR& argv_rng) {
        try {
            return this->parse_known_args(argv_rng);
        }
        catch (const ap::argument_parser_exception& err) {
            std::cerr << "[ap::error] " << err.what() << std::endl
                      << this->resolved_parser() << std::endl;
            std::exit(EXIT_FAILURE);
        }
    }
 
    [[nodiscard]] std::string_view name() const noexcept {
        return this->_name;
    }
 
    [[nodiscard]] std::string_view program_name() const noexcept {
        return this->_program_name;
    }
 
    [[nodiscard]] bool invoked() const noexcept {
        return this->_invoked;
    }
 
    [[nodiscard]] bool finalized() const noexcept {
        return this->_finalized;
    }
 
    [[nodiscard]] argument_parser& resolved_parser() noexcept {
        const auto used_subparser_it = std::ranges::find_if(
            this->_subparsers, [](const auto& subparser) { return subparser->_invoked; }
        );
        if (used_subparser_it == this->_subparsers.end())
            return *this;
        return (*used_subparser_it)->resolved_parser();
    }
 
    [[nodiscard]] bool is_used(std::string_view arg_name) const noexcept {
        const auto arg = this->_get_argument(arg_name);
        return arg ? arg->is_used() : false;
    }
 
    [[nodiscard]] bool has_value(std::string_view arg_name) const noexcept {
        const auto arg = this->_get_argument(arg_name);
        return arg ? arg->has_value() : false;
    }
 
    [[nodiscard]] std::size_t count(std::string_view arg_name) const noexcept {
        const auto arg = this->_get_argument(arg_name);
        return arg ? arg->count() : 0ull;
    }
 
    template <util::c_argument_value_type T = std::string>
    [[nodiscard]] T value(std::string_view arg_name) const {
        const auto arg = this->_get_argument(arg_name);
        if (not arg)
            throw lookup_failure::argument_not_found(arg_name);
 
        const auto& arg_value = arg->value();
        try {
            return std::any_cast<T>(arg_value);
        }
        catch (const std::bad_any_cast&) {
            throw type_error::invalid_value_type<T>(arg->name());
        }
    }
 
    template <util::c_argument_value_type T = std::string, std::convertible_to<T> U>
    [[nodiscard]] T value_or(std::string_view arg_name, U&& fallback_value) const {
        const auto arg = this->_get_argument(arg_name);
        if (not arg)
            throw lookup_failure::argument_not_found(arg_name);
 
        try {
            const auto& arg_value = arg->value();
            return std::any_cast<T>(arg_value);
        }
        catch (const std::logic_error&) {
            // positional: no value parsed
            // optional: no value parsed + no predefined value
            return T{std::forward<U>(fallback_value)};
        }
        catch (const std::bad_any_cast&) {
            throw type_error::invalid_value_type<T>(arg->name());
        }
    }
 
    template <util::c_argument_value_type T = std::string>
    [[nodiscard]] std::vector<T> values(std::string_view arg_name) const {
        const auto arg = this->_get_argument(arg_name);
        if (not arg)
            throw lookup_failure::argument_not_found(arg_name);
 
        try {
            std::vector<T> values;
            // TODO: use std::ranges::to after transition to C++23
            std::ranges::copy(
                util::any_range_cast_view<T>(arg->values()), std::back_inserter(values)
            );
            return values;
        }
        catch (const std::bad_any_cast&) {
            throw type_error::invalid_value_type<T>(arg->name());
        }
    }
 
    void print_help(const bool verbose, std::ostream& os = std::cout) const noexcept {
        os << "Program: " << this->_program_name;
        if (this->_program_version)
            os << " (" << this->_program_version.value() << ')';
        os << '\n';
 
        if (this->_program_description)
            os << '\n'
               << std::string(this->_indent_width, ' ') << this->_program_description.value()
               << '\n';
 
        this->_print_subparsers(os);
        for (const auto& group : this->_argument_groups)
            this->_print_group(os, *group, verbose);
    }
 
    void print_version(std::ostream& os = std::cout) const noexcept {
        os << this->_program_name << " : version " << this->_program_version.value_or("unspecified")
           << std::endl;
    }
 
    friend std::ostream& operator<<(std::ostream& os, const argument_parser& parser) noexcept {
        parser.print_help(parser._verbose, os);
        return os;
    }
 
#ifdef AP_TESTING
    friend struct ::ap_testing::argument_parser_test_fixture;
#endif
 
private:
    using arg_ptr_t = std::shared_ptr<detail::argument_base>;
    using arg_ptr_vec_t = std::vector<arg_ptr_t>;
    using arg_ptr_vec_iter_t = typename arg_ptr_vec_t::iterator;
 
    using arg_group_ptr_t = std::unique_ptr<argument_group>;
    using arg_group_ptr_vec_t = std::vector<arg_group_ptr_t>;
 
    using arg_parser_ptr_t = std::unique_ptr<argument_parser>;
    using arg_parser_ptr_vec_t = std::vector<arg_parser_ptr_t>;
 
    using arg_token_vec_t = std::vector<detail::argument_token>;
    using arg_token_vec_iter_t = typename arg_token_vec_t::const_iterator;
 
    struct parsing_state {
        parsing_state(argument_parser& parser, const bool parse_known_only = false)
        : curr_arg(nullptr),
          curr_pos_arg_it(parser._positional_args.begin()),
          parse_known_only(parse_known_only) {}
 
        void set_parser(argument_parser& parser) {
            this->curr_arg = nullptr;
            this->curr_pos_arg_it = parser._positional_args.begin();
        }
 
        arg_ptr_t curr_arg; 
        arg_ptr_vec_iter_t
            curr_pos_arg_it; 
        const bool
            parse_known_only; 
        std::vector<std::string> unknown_args = {}; 
    };
 
    argument_parser(const std::string_view name, const std::string_view parent_name)
    : _name(name),
      _program_name(
          std::format("{}{}{}", parent_name, std::string(not parent_name.empty(), ' '), name)
      ),
      _gr_positional_args(add_group("Positional Arguments")),
      _gr_optional_args(add_group("Optional Arguments")) {
        if (name.empty())
            throw invalid_configuration("The program name cannot be empty!");
 
        if (util::contains_whitespaces(name))
            throw invalid_configuration("The program name cannot contain whitespace characters!");
    }
 
    void _verify_arg_name_pattern(const std::string_view arg_name) const {
        if (arg_name.empty())
            throw invalid_configuration::invalid_argument_name(
                arg_name, "An argument name cannot be empty."
            );
 
        if (util::contains_whitespaces(arg_name))
            throw invalid_configuration::invalid_argument_name(
                arg_name, "An argument name cannot contain whitespaces."
            );
 
        if (arg_name.front() == this->_flag_prefix_char)
            throw invalid_configuration::invalid_argument_name(
                arg_name,
                std::format(
                    "An argument name cannot begin with a flag prefix character ({}).",
                    this->_flag_prefix_char
                )
            );
 
        if (std::isdigit(arg_name.front()))
            throw invalid_configuration::invalid_argument_name(
                arg_name, "An argument name cannot begin with a digit."
            );
    }
 
    [[nodiscard]] auto _name_match_predicate(
        const std::string_view arg_name,
        const detail::argument_name::match_type m_type = detail::argument_name::m_any
    ) const noexcept {
        return [=](const arg_ptr_t& arg) { return arg->name().match(arg_name, m_type); };
    }
 
    [[nodiscard]] auto _name_match_predicate(
        const detail::argument_name& arg_name,
        const detail::argument_name::match_type m_type = detail::argument_name::m_any
    ) const noexcept {
        return [&arg_name, m_type](const arg_ptr_t& arg) {
            return arg->name().match(arg_name, m_type);
        };
    }
 
    [[nodiscard]] bool _is_arg_name_used(
        const detail::argument_name& arg_name,
        const detail::argument_name::match_type m_type = detail::argument_name::m_any
    ) const noexcept {
        const auto predicate = this->_name_match_predicate(arg_name, m_type);
 
        if (std::ranges::find_if(this->_positional_args, predicate) != this->_positional_args.end())
            return true;
 
        if (std::ranges::find_if(this->_optional_args, predicate) != this->_optional_args.end())
            return true;
 
        return false;
    }
 
    void _validate_group(const argument_group& group) {
        if (group._parser != this)
            throw std::logic_error(std::format(
                "An argument group '{}' does not belong to the given parser.", group._name
            ));
    }
 
    template <util::c_forward_iterator_of<std::string, util::type_validator::convertible> AIt>
    void _parse_args_impl(AIt args_begin, const AIt args_end, parsing_state& state) {
        this->_invoked = true;
 
        if (args_begin != args_end) {
            // try to match a subparser
            const auto subparser_it =
                std::ranges::find(this->_subparsers, *args_begin, [](const auto& subparser) {
                    return subparser->_name;
                });
            if (subparser_it != this->_subparsers.end()) {
                auto& subparser = **subparser_it;
                state.set_parser(subparser);
                subparser._parse_args_impl(++args_begin, args_end, state);
                return;
            }
        }
 
        // process command-line arguments within the current parser
        this->_validate_argument_configuration();
        for (const auto& tok : this->_tokenize(args_begin, args_end, state))
            this->_parse_token(tok, state);
        this->_verify_final_state();
        this->_finalized = true;
    }
 
    void _validate_argument_configuration() const {
        // step 1
        arg_ptr_t non_required_arg = nullptr;
        for (const auto& arg : this->_positional_args) {
            if (not arg->is_required()) {
                non_required_arg = arg;
                continue;
            }
 
            if (non_required_arg and arg->is_required())
                throw invalid_configuration(std::format(
                    "Required positional argument [{}] cannot be defined after a non-required "
                    "positional argument [{}].",
                    arg->name().str(),
                    non_required_arg->name().str()
                ));
        }
    }
 
    template <util::c_forward_iterator_of<std::string, util::type_validator::convertible> AIt>
    [[nodiscard]] arg_token_vec_t _tokenize(
        AIt args_begin, const AIt args_end, const parsing_state& state
    ) {
        arg_token_vec_t toks;
        toks.reserve(static_cast<std::size_t>(std::ranges::distance(args_begin, args_end)));
        std::ranges::for_each(args_begin, args_end, [&](const auto& arg_value) {
            this->_tokenize_arg(arg_value, toks, state);
        });
        return toks;
    }
 
    void _tokenize_arg(
        const std::string_view arg_value, arg_token_vec_t& toks, const parsing_state& state
    ) {
        detail::argument_token tok{
            .type = this->_deduce_token_type(arg_value), .value = std::string(arg_value)
        };
 
        if (not tok.is_flag_token() or this->_validate_flag_token(tok)) {
            toks.emplace_back(std::move(tok));
            return;
        }
 
        // not a value token -> flag token
        // flag token could not be validated -> unknown flag
        if (state.parse_known_only) { // do nothing (will be handled during parsing)
            toks.emplace_back(std::move(tok));
            return;
        }
 
        switch (this->_unknown_policy) {
        case unknown_policy::fail:
            throw parsing_failure::unknown_argument(tok.value);
        case unknown_policy::warn:
            std::cerr << "[ap::warning] Unknown argument '" << tok.value << "' will be ignored."
                      << std::endl;
            [[fallthrough]];
        case unknown_policy::ignore:
            return;
        case unknown_policy::as_values:
            tok.type = detail::argument_token::t_value;
            toks.emplace_back(std::move(tok));
            break;
        }
    }
 
    [[nodiscard]] detail::argument_token::token_type _deduce_token_type(
        const std::string_view arg_value
    ) const noexcept {
        if (util::contains_whitespaces(arg_value))
            return detail::argument_token::t_value;
 
        if (arg_value.starts_with(this->_flag_prefix))
            return detail::argument_token::t_flag_primary;
 
        if (arg_value.starts_with(this->_flag_prefix_char))
            return detail::argument_token::t_flag_secondary;
 
        return detail::argument_token::t_value;
    }
 
    [[nodiscard]] bool _validate_flag_token(detail::argument_token& tok) noexcept {
        const auto opt_arg_it = this->_find_opt_arg(tok);
        if (opt_arg_it == this->_optional_args.end())
            return this->_validate_compound_flag_token(tok);
 
        tok.args.emplace_back(*opt_arg_it);
        return true;
    }
 
    bool _validate_compound_flag_token(detail::argument_token& tok) noexcept {
        if (tok.type != detail::argument_token::t_flag_secondary)
            return false;
 
        const auto actual_tok_value = this->_strip_flag_prefix(tok);
        tok.args.reserve(actual_tok_value.size());
 
        for (const char c : actual_tok_value) {
            const auto opt_arg_it = std::ranges::find_if(
                this->_optional_args,
                this->_name_match_predicate(
                    std::string_view(&c, 1ull), detail::argument_name::m_secondary
                )
            );
 
            if (opt_arg_it == this->_optional_args.end()) {
                tok.args.clear();
                return false;
            }
 
            tok.args.emplace_back(*opt_arg_it);
        }
 
        tok.type = detail::argument_token::t_flag_compound;
        return true;
    }
 
    [[nodiscard]] arg_ptr_vec_iter_t _find_opt_arg(const detail::argument_token& flag_tok
    ) noexcept {
        if (not flag_tok.is_flag_token())
            return this->_optional_args.end();
 
        const auto actual_tok_value = this->_strip_flag_prefix(flag_tok);
        const auto match_type =
            flag_tok.type == detail::argument_token::t_flag_primary
                ? detail::argument_name::m_primary
                : detail::argument_name::m_secondary;
 
        return std::ranges::find_if(
            this->_optional_args, this->_name_match_predicate(actual_tok_value, match_type)
        );
    }
 
    [[nodiscard]] std::string_view _strip_flag_prefix(const detail::argument_token& tok
    ) const noexcept {
        switch (tok.type) {
        case detail::argument_token::t_flag_primary:
            return std::string_view(tok.value).substr(this->_primary_flag_prefix_length);
        case detail::argument_token::t_flag_secondary:
            return std::string_view(tok.value).substr(this->_secondary_flag_prefix_length);
        default:
            return tok.value;
        }
    }
 
    void _parse_token(const detail::argument_token& tok, parsing_state& state) {
        if (state.curr_arg and state.curr_arg->is_greedy()) {
            this->_set_argument_value(tok.value, state);
            return;
        }
 
        if (tok.is_flag_token())
            this->_parse_flag_token(tok, state);
        else
            this->_parse_value_token(tok, state);
    }
 
    void _parse_flag_token(const detail::argument_token& tok, parsing_state& state) {
        if (not tok.is_valid_flag_token()) {
            if (state.parse_known_only) {
                state.curr_arg.reset();
                state.unknown_args.emplace_back(tok.value);
                return;
            }
            else {
                // should never happen as unknown flags are filtered out during tokenization
                throw parsing_failure::unknown_argument(tok.value);
            }
        }
 
        for (const auto& arg : tok.args) {
            if (arg->mark_used())
                state.curr_arg = arg;
            else
                state.curr_arg.reset();
        }
    }
 
    void _parse_value_token(const detail::argument_token& tok, parsing_state& state) {
        if (not state.curr_arg) {
            if (state.curr_pos_arg_it == this->_positional_args.end()) {
                state.unknown_args.emplace_back(tok.value);
                return;
            }
 
            state.curr_arg = *state.curr_pos_arg_it;
        }
 
        this->_set_argument_value(tok.value, state);
    }
 
    void _set_argument_value(const std::string_view value, parsing_state& state) noexcept {
        if (state.curr_arg->set_value(std::string(value)))
            return; // argument still accepts values
 
        // advance to the next positional argument if possible
        if (state.curr_arg->is_positional()
            and state.curr_pos_arg_it != this->_positional_args.end())
            ++state.curr_pos_arg_it;
 
        state.curr_arg.reset();
    }
 
    void _verify_final_state() const {
        const auto [supress_group_checks, suppress_arg_checks] = this->_are_checks_suppressed();
        for (const auto& group : this->_argument_groups)
            this->_verify_group_requirements(*group, supress_group_checks, suppress_arg_checks);
    }
 
    [[nodiscard]] std::pair<bool, bool> _are_checks_suppressed() const noexcept {
        bool suppress_group_checks = false;
        bool suppress_arg_checks = false;
 
        auto check_arg = [&](const arg_ptr_t& arg) {
            if (arg->is_used()) {
                if (arg->suppresses_group_checks())
                    suppress_group_checks = true;
                if (arg->suppresses_arg_checks())
                    suppress_arg_checks = true;
            }
        };
 
        // TODO: use std::views::join after the transition to C++23
        std::ranges::for_each(this->_positional_args, check_arg);
        std::ranges::for_each(this->_optional_args, check_arg);
        return {suppress_group_checks, suppress_arg_checks};
    }
 
    void _verify_group_requirements(
        const argument_group& group,
        const bool suppress_group_checks,
        const bool suppress_arg_checks
    ) const {
        if (group._arguments.empty())
            return;
 
        if (not suppress_group_checks) {
            const auto n_used_args = static_cast<std::size_t>(std::ranges::count_if(
                group._arguments, [](const auto& arg) { return arg->is_used(); }
            ));
 
            if (group._mutually_exclusive) {
                if (n_used_args > 1ull)
                    throw parsing_failure(std::format(
                        "At most one argument from the mutually exclusive group '{}' can be used",
                        group._name
                    ));
 
                const auto used_arg_it = std::ranges::find_if(
                    group._arguments, [](const auto& arg) { return arg->is_used(); }
                );
 
                if (used_arg_it != group._arguments.end()) {
                    // only the one used argument has to be validated
                    this->_verify_argument_requirements(*used_arg_it, suppress_arg_checks);
                    return;
                }
            }
 
            if (group._required and n_used_args == 0ull)
                throw parsing_failure(std::format(
                    "At least one argument from the required group '{}' must be used", group._name
                ));
        }
 
        // all arguments in the group have to be validated
        for (const auto& arg : group._arguments)
            this->_verify_argument_requirements(arg, suppress_arg_checks);
    }
 
    void _verify_argument_requirements(const arg_ptr_t& arg, const bool suppress_arg_checks) const {
        if (suppress_arg_checks)
            return;
 
        if (arg->is_required() and not arg->has_value())
            throw parsing_failure(
                std::format("No values parsed for a required argument [{}]", arg->name().str())
            );
        if (const auto nv_ord = arg->nvalues_ordering(); not std::is_eq(nv_ord))
            throw parsing_failure::invalid_nvalues(arg->name(), nv_ord);
    }
 
    arg_ptr_t _get_argument(std::string_view arg_name) const noexcept {
        const auto predicate = this->_name_match_predicate(arg_name);
 
        if (auto pos_arg_it = std::ranges::find_if(this->_positional_args, predicate);
            pos_arg_it != this->_positional_args.end()) {
            return *pos_arg_it;
        }
 
        if (auto opt_arg_it = std::ranges::find_if(this->_optional_args, predicate);
            opt_arg_it != this->_optional_args.end()) {
            return *opt_arg_it;
        }
 
        return nullptr;
    }
 
    void _print_subparsers(std::ostream& os) const noexcept {
        if (this->_subparsers.empty())
            return;
 
        os << "\nCommands:\n";
 
        std::vector<detail::help_builder> builders;
        builders.reserve(this->_subparsers.size());
 
        for (const auto& subparser : this->_subparsers)
            builders.emplace_back(subparser->_name, subparser->_program_description);
 
        std::size_t max_subparser_name_length = 0ull;
        for (const auto& bld : builders)
            max_subparser_name_length = std::max(max_subparser_name_length, bld.name.length());
 
        for (const auto& bld : builders)
            os << '\n' << bld.get_basic(this->_indent_width, max_subparser_name_length);
 
        os << '\n';
    }
 
    void _print_group(std::ostream& os, const argument_group& group, const bool verbose)
        const noexcept {
        auto visible_args = std::views::filter(group._arguments, [](const auto& arg) {
            return not arg->is_hidden();
        });
 
        if (std::ranges::empty(visible_args))
            return;
 
        os << '\n' << group._name << ":";
 
        std::vector<std::string> group_attrs;
        if (group._required)
            group_attrs.emplace_back("required");
        if (group._mutually_exclusive)
            group_attrs.emplace_back("mutually exclusive");
        if (not group_attrs.empty())
            os << " (" << util::join(group_attrs) << ')';
 
        os << '\n';
 
        if (verbose) {
            for (const auto& arg : visible_args)
                os << '\n' << arg->help_builder(verbose).get(this->_indent_width) << '\n';
        }
        else {
            std::vector<detail::help_builder> builders;
            builders.reserve(group._arguments.size());
 
            for (const auto& arg : visible_args)
                builders.emplace_back(arg->help_builder(verbose));
 
            std::size_t max_arg_name_length = 0ull;
            for (const auto& bld : builders)
                max_arg_name_length = std::max(max_arg_name_length, bld.name.length());
 
            for (const auto& bld : builders)
                os << '\n' << bld.get_basic(this->_indent_width, max_arg_name_length);
 
            os << '\n';
        }
    }
 
    std::string _name; 
    std::string
        _program_name; 
    std::optional<std::string> _program_version; 
    std::optional<std::string> _program_description; 
    bool _verbose = false; 
    unknown_policy _unknown_policy = unknown_policy::fail; 
 
    arg_ptr_vec_t _positional_args; 
    arg_ptr_vec_t _optional_args; 
    arg_group_ptr_vec_t _argument_groups; 
    argument_group& _gr_positional_args; 
    argument_group& _gr_optional_args; 
    arg_parser_ptr_vec_t _subparsers; 
 
    bool _invoked =
        false; 
    bool _finalized = false; 
 
    static constexpr std::uint8_t _primary_flag_prefix_length = 2u;
    static constexpr std::uint8_t _secondary_flag_prefix_length = 1u;
    static constexpr char _flag_prefix_char = '-';
    static constexpr std::string_view _flag_prefix = "--";
    static constexpr std::uint8_t _indent_width = 2;
};
 
namespace detail {
 
inline void add_default_argument(
    const default_argument arg_discriminator, argument_parser& arg_parser
) noexcept {
    switch (arg_discriminator) {
    case default_argument::p_input:
        arg_parser.add_positional_argument("input")
            .action<action_type::observe>(action::check_file_exists())
            .help("Input file path");
        break;
 
    case default_argument::p_output:
        arg_parser.add_positional_argument("output").help("Output file path");
        break;
 
    case default_argument::o_help:
        arg_parser.add_optional_argument<none_type>("help", "h")
            .action<action_type::on_flag>(action::print_help(arg_parser, EXIT_SUCCESS))
            .help("Display the help message");
        break;
 
    case default_argument::o_version:
        arg_parser.add_optional_argument<none_type>("version", "v")
            .action<action_type::on_flag>([&arg_parser]() {
                arg_parser.print_version();
                std::exit(EXIT_SUCCESS);
            })
            .help("Dsiplay program version info");
        break;
 
    case default_argument::o_input:
        arg_parser.add_optional_argument("input", "i")
            .nargs(1ull)
            .action<action_type::observe>(action::check_file_exists())
            .help("Input file path");
        break;
 
    case default_argument::o_output:
        arg_parser.add_optional_argument("output", "o").nargs(1ull).help("Output file path");
        break;
 
    case default_argument::o_multi_input:
        arg_parser.add_optional_argument("input", "i")
            .nargs(ap::nargs::at_least(1ull))
            .action<action_type::observe>(action::check_file_exists())
            .help("Input files paths");
        break;
 
    case default_argument::o_multi_output:
        arg_parser.add_optional_argument("output", "o")
            .nargs(ap::nargs::at_least(1ull))
            .help("Output files paths");
        break;
    }
}
 
} // namespace detail
 
} // namespace ap