argument.hpp

Go to the documentation of this file.

// 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 "action/predefined.hpp"
#include "action/util/helpers.hpp"
#include "detail/argument_base.hpp"
#include "detail/help_builder.hpp"
#include "nargs/range.hpp"
#include "types.hpp"
#include "util/concepts.hpp"
#include "util/ranges.hpp"
 
#ifdef AP_TESTING
 
namespace ap_testing {
struct argument_test_fixture;
} // namespace ap_testing
 
#endif
 
namespace ap {
 
enum class argument_type : bool { positional, optional };
 
template <argument_type ArgT, util::c_argument_value_type T = std::string>
class argument : public detail::argument_base {
public:
    using value_type = T; 
    using count_type = nargs::count_type; 
 
    static constexpr argument_type type = ArgT; 
 
    argument() = delete;
 
    argument(const detail::argument_name& name)
    requires(type == argument_type::positional)
    : _name(name), _nargs_range(_default_nargs_range_actual), _required(_default_required) {}
 
    argument(const detail::argument_name& name)
    requires(type == argument_type::optional)
    : _name(name),
      _nargs_range(_default_nargs_range_actual),
      _required(_default_required),
      _count(0ull) {}
 
    [[nodiscard]] bool is_positional() const noexcept override {
        return type == argument_type::positional;
    }
 
    [[nodiscard]] bool is_optional() const noexcept override {
        return type == argument_type::optional;
    }
 
    [[nodiscard]] const ap::detail::argument_name& name() const noexcept override {
        return this->_name;
    }
 
    [[nodiscard]] const std::optional<std::string>& help() const noexcept override {
        return this->_help_msg;
    }
 
    [[nodiscard]] bool is_hidden() const noexcept override {
        return this->_hidden;
    }
 
    [[nodiscard]] bool is_required() const noexcept override {
        return this->_required;
    }
 
    [[nodiscard]] bool suppresses_arg_checks() const noexcept override {
        return this->_suppress_arg_checks;
    }
 
    [[nodiscard]] bool suppresses_group_checks() const noexcept override {
        return this->_suppress_group_checks;
    }
 
    [[nodiscard]] bool is_greedy() const noexcept override {
        return this->_greedy;
    }
 
    // attribute setters
 
    argument& help(std::string_view help_msg) noexcept {
        this->_help_msg = help_msg;
        return *this;
    }
 
    argument& hidden(const bool h = true) noexcept {
        this->_hidden = h;
        return *this;
    }
 
    argument& required(const bool value = true) {
        if (value and (this->_suppress_arg_checks or this->_suppress_group_checks))
            throw invalid_configuration(
                std::format("A suppressing argument [{}] cannot be required!", this->_name.str())
            );
 
        this->_required = value;
        return *this;
    }
 
    argument& suppress_arg_checks(const bool value = true) {
        if (value and this->_required)
            throw invalid_configuration(std::format(
                "A required argument [{}] cannot suppress argument checks!", this->_name.str()
            ));
 
        this->_suppress_arg_checks = value;
        return *this;
    }
 
    argument& suppress_group_checks(const bool value = true) {
        if (value and this->_required)
            throw invalid_configuration(std::format(
                "A required argument [{}] cannot suppress argument group checks!", this->_name.str()
            ));
 
        this->_suppress_group_checks = value;
        return *this;
    }
 
    argument& greedy(const bool value = true) noexcept
    requires(not util::c_is_none<value_type>)
    {
        this->_greedy = value;
        return *this;
    }
 
    argument& nargs(const nargs::range& range) noexcept
    requires(not util::c_is_none<value_type>)
    {
        this->_nargs_range = range;
        return *this;
    }
 
    argument& nargs(const count_type n) noexcept
    requires(not util::c_is_none<value_type>)
    {
        return this->nargs(nargs::range(n));
    }
 
    argument& nargs(const count_type lower, const count_type upper) noexcept
    requires(not util::c_is_none<value_type>)
    {
        return this->nargs(nargs::range(lower, upper));
    }
 
    template <action::util::c_value_action_specifier AS, typename F>
    argument& action(F&& action) noexcept
    requires(not util::c_is_none<value_type>)
    {
        using callable_type = action::util::callable_type<AS, value_type>;
        this->_value_actions.emplace_back(std::forward<callable_type>(action));
        return *this;
    }
 
    template <action::util::c_flag_action_specifier AS, typename F>
    argument& action(F&& action) noexcept
    requires(type == argument_type::optional)
    {
        this->_flag_actions.emplace_back(std::forward<flag_action_type>(action));
        return *this;
    }
 
    template <util::c_range_of<value_type, util::type_validator::convertible> CR>
    argument& choices(const CR& choices) noexcept
    requires(not util::c_is_none<value_type> and std::equality_comparable<value_type>)
    {
        for (const auto& choice : choices)
            this->_choices.emplace_back(choice);
        return *this;
    }
 
    argument& choices(std::initializer_list<value_type> choices) noexcept
    requires(not util::c_is_none<value_type> and std::equality_comparable<value_type>)
    {
        return this->choices<>(choices);
    }
 
    argument& choices(const std::convertible_to<value_type> auto&... choices) noexcept
    requires(not util::c_is_none<value_type> and std::equality_comparable<value_type>)
    {
        (this->_choices.emplace_back(choices), ...);
        return *this;
    }
 
    template <util::c_range_of<value_type, util::type_validator::convertible> CR>
    argument& default_values(const CR& values) noexcept
    requires(not util::c_is_none<value_type> and std::equality_comparable<value_type>)
    {
        for (const auto& value : values)
            this->_default_values.emplace_back(std::make_any<value_type>(value));
        this->_required = false;
        return *this;
    }
 
    argument& default_values(std::initializer_list<value_type> values) noexcept
    requires(not util::c_is_none<value_type> and std::equality_comparable<value_type>)
    {
        return this->default_values<>(values);
    }
 
    argument& default_values(const std::convertible_to<value_type> auto&... values) noexcept
    requires(not util::c_is_none<value_type>)
    {
        (this->_default_values.emplace_back(std::make_any<value_type>(values)), ...);
        this->_required = false;
        return *this;
    }
 
    template <util::c_range_of<value_type, util::type_validator::convertible> CR>
    argument& implicit_values(const CR& values) noexcept
    requires(not util::c_is_none<value_type> and type == argument_type::optional)
    {
        for (const auto& value : values)
            this->_implicit_values.emplace_back(std::make_any<value_type>(value));
        return *this;
    }
 
    argument& implicit_values(std::initializer_list<value_type> values) noexcept
    requires(not util::c_is_none<value_type> and type == argument_type::optional)
    {
        return this->implicit_values<>(values);
    }
 
    argument& implicit_values(const std::convertible_to<value_type> auto&... values) noexcept
    requires(not util::c_is_none<value_type> and type == argument_type::optional)
    {
        (this->_implicit_values.emplace_back(std::make_any<value_type>(values)), ...);
        return *this;
    }
 
#ifdef AP_TESTING
    friend struct ::ap_testing::argument_test_fixture;
#endif
 
private:
    using value_action_type = action::util::value_action_variant_type<T>;
 
    using flag_action_type = typename action_type::on_flag::type;
 
    template <typename _T>
    using value_arg_specific_type = std::conditional_t<
        util::c_is_none<value_type>,
        none_type,
        _T>; 
 
    template <typename _T>
    using positional_specific_type =
        std::conditional_t<type == argument_type::positional, _T, none_type>;
 
    template <typename _T>
    using optional_specific_type =
        std::conditional_t<type == argument_type::optional, _T, none_type>;
 
    [[nodiscard]] detail::help_builder help_builder(const bool verbose) const noexcept override {
        detail::help_builder bld(this->_name.str(), this->_help_msg);
 
        if (not verbose)
            return bld;
 
        bld.params.reserve(6ull);
        if (this->_required != _default_required)
            bld.add_param("required", std::format("{}", this->_required));
        if (this->_suppress_arg_checks)
            bld.add_param("suppress arg checks", "true");
        if (this->_suppress_group_checks)
            bld.add_param("suppress group checks", "true");
        if (this->_nargs_range != _default_nargs_range)
            bld.add_param("nargs", this->_nargs_range);
        if constexpr (util::c_writable<value_type>) {
            if (not this->_choices.empty())
                bld.add_range_param("choices", this->_choices);
            if (not this->_default_values.empty())
                bld.add_range_param(
                    "default value(s)", util::any_range_cast_view<value_type>(this->_default_values)
                );
            if constexpr (type == argument_type::optional) {
                if (not this->_implicit_values.empty())
                    bld.add_range_param(
                        "implicit value(s)",
                        util::any_range_cast_view<value_type>(this->_implicit_values)
                    );
            }
        }
 
        return bld;
    }
 
    bool mark_used() override {
        if constexpr (type == argument_type::optional) {
            ++this->_count;
            for (const auto& action : this->_flag_actions)
                action();
        }
 
        return this->_accepts_further_values();
    }
 
    [[nodiscard]] bool is_used() const noexcept override {
        return this->count() > 0ull;
    }
 
    [[nodiscard]] std::size_t count() const noexcept override {
        if constexpr (type == argument_type::optional)
            return this->_count;
        else
            return static_cast<std::size_t>(this->has_parsed_values());
    }
 
    bool set_value(const std::string& str_value) override {
        return this->_set_value_impl(str_value);
    }
 
    [[nodiscard]] bool has_value() const noexcept override {
        return this->has_parsed_values() or this->_has_predefined_values_impl();
    }
 
    [[nodiscard]] bool has_parsed_values() const noexcept override {
        return not this->_values.empty();
    }
 
    [[nodiscard]] bool has_predefined_values() const noexcept override {
        return this->_has_predefined_values_impl();
    }
 
    [[nodiscard]] std::weak_ordering nvalues_ordering() const noexcept override {
        if (this->_values.empty() and this->_has_predefined_values_impl())
            return std::weak_ordering::equivalent;
 
        return this->_values.size() <=> this->_nargs_range;
    }
 
    [[nodiscard]] const std::any& value() const override {
        if (this->has_parsed_values())
            return this->_values.front();
 
        if constexpr (util::c_is_none<value_type>)
            throw std::logic_error(
                std::format("No values parsed for argument '{}'.", this->_name.str())
            );
        else
            return this->_predefined_values().front();
    }
 
    [[nodiscard]] const std::vector<std::any>& values() const override {
        return this->_values_impl();
    }
 
    [[nodiscard]] const std::vector<std::any>& _values_impl() const noexcept
    requires(util::c_is_none<value_type>)
    {
        return this->_values;
    }
 
    [[nodiscard]] const std::vector<std::any>& _values_impl() const noexcept
    requires(not util::c_is_none<value_type>)
    {
        if (this->has_parsed_values())
            return this->_values;
 
        try {
            return this->_predefined_values();
        }
        catch (const std::logic_error&) {
            return this->_values; // fallback: empty vector
        }
    }
 
    [[nodiscard]] bool _has_predefined_values_impl() const noexcept
    requires(util::c_is_none<value_type>)
    {
        return false;
    }
 
    [[nodiscard]] bool _has_predefined_values_impl() const noexcept
    requires(not util::c_is_none<value_type>)
    {
        if constexpr (type == argument_type::positional)
            return not this->_default_values.empty();
        else
            return not this->_default_values.empty()
                or (this->is_used() and not this->_implicit_values.empty());
    }
 
    [[nodiscard]] const std::vector<std::any>& _predefined_values() const
    requires(not util::c_is_none<value_type>)
    {
        if constexpr (type == argument_type::optional) {
            if (this->is_used()) {
                if (this->_implicit_values.empty())
                    throw(std::logic_error(std::format(
                        "No implicit values specified for argument '{}'.", this->_name.str()
                    )));
 
                return this->_implicit_values;
            }
        }
 
        if (this->_default_values.empty())
            throw(std::logic_error(
                std::format("No default values specified for argument '{}'.", this->_name.str())
            ));
 
        return this->_default_values;
    }
 
    [[nodiscard]] bool _accepts_further_values() const noexcept {
        return not std::is_gt(this->_values.size() + 1ull <=> this->_nargs_range);
    }
 
    [[nodiscard]] bool _is_valid_choice(const value_type& value) const noexcept
    requires(not util::c_is_none<value_type>)
    {
        return this->_choices.empty()
            or std::ranges::find(this->_choices, value) != this->_choices.end();
    }
 
    bool _set_value_impl(const std::string& str_value)
    requires(util::c_is_none<value_type>)
    {
        throw parsing_failure(std::format(
            "Cannot set values for a none-type argument '{}' (value: '{}')",
            this->_name.str(),
            str_value
        ));
    }
 
    bool _set_value_impl(const std::string& str_value)
    requires(not util::c_is_none<value_type>)
    {
        if (not this->_accepts_further_values())
            throw parsing_failure::invalid_nvalues(this->_name, std::weak_ordering::greater);
 
        value_type value;
        if constexpr (util::c_trivially_readable<value_type>) {
            value = value_type(str_value);
        }
        else {
            if (not (std::istringstream(str_value) >> value))
                throw parsing_failure(std::format(
                    "Cannot parse value `{}` for argument [{}].", str_value, this->_name.str()
                ));
        }
 
        if (not this->_is_valid_choice(value))
            throw parsing_failure(std::format(
                "Value `{}` is not a valid choice for argument [{}].", str_value, this->_name.str()
            ));
 
        const auto apply_visitor = action::util::apply_visitor<value_type>{value};
        for (const auto& action : this->_value_actions)
            std::visit(apply_visitor, action);
 
        this->_values.emplace_back(std::move(value));
        return this->_accepts_further_values();
    }
 
    // attributes
    const ap::detail::argument_name _name; 
    std::optional<std::string> _help_msg; 
    nargs::range _nargs_range; 
    [[no_unique_address]] value_arg_specific_type<std::vector<std::any>>
        _default_values; 
    [[no_unique_address]] value_arg_specific_type<optional_specific_type<std::vector<std::any>>>
        _implicit_values; 
    [[no_unique_address]] value_arg_specific_type<std::vector<value_type>>
        _choices; 
    [[no_unique_address]] optional_specific_type<std::vector<flag_action_type>>
        _flag_actions; 
    [[no_unique_address]] value_arg_specific_type<std::vector<value_action_type>>
        _value_actions; 
 
    bool _required : 1; 
    bool _suppress_arg_checks : 1 =
        false; 
    bool _suppress_group_checks : 1 =
        false; 
    bool _greedy : 1 = false; 
    bool _hidden : 1 = false; 
 
    // parsing result
    [[no_unique_address]] optional_specific_type<std::size_t>
        _count; 
    std::vector<std::any> _values; 
 
    // default attribute values
    static constexpr bool _default_required = (type == argument_type::positional);
    static constexpr nargs::range _default_nargs_range =
        (type == argument_type::positional) ? nargs::range(1ull) : nargs::any();
    static constexpr nargs::range _default_nargs_range_actual =
        util::c_is_none<value_type> ? nargs::range(0ull) : _default_nargs_range;
};
 
template <util::c_argument_value_type T = std::string>
using positional_argument = argument<argument_type::positional, T>;
 
template <util::c_argument_value_type T = std::string>
using optional_argument = argument<argument_type::optional, T>;
 
} // namespace ap