argument_parser.hpp

Go to the documentation of this file.

// Copyright (c) 2023-2026 Jakub Musiał
// This file is part of the CPP-ARGON project (https://github.com/SpectraL519/cpp-argon).
// Licensed under the MIT License. See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include "argon/argument.hpp"
#include "argon/argument_group.hpp"
#include "argon/detail/argument_token.hpp"
#include "argon/types.hpp"
#include "argon/util/ranges.hpp"
 
#include <algorithm>
#include <format>
#include <iostream>
#include <ranges>
#include <span>
 
#ifdef AP_TESTING
 
namespace argon_testing {
struct argument_parser_test_fixture;
} // namespace argon_testing
 
#endif
 
namespace argon {
 
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 argon::argument_parser_exception& err) {
            std::cerr << "[argon::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 argon::argument_parser_exception& err) {
            std::cerr << "[argon::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;
            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 ::argon_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 << "[argon::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::concat after the transition to C++26
        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 {
 if (group._hidden)
 return;
 
 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_view> 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(argon::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(argon::nargs::at_least(1ull))
            .help("Output files paths");
 break;
    }
}
 
} // namespace detail
 
} // namespace argon