argument.hh

Go to the documentation of this file.

#pragma once
 
#include <algorithm>
#include <filesystem>
#include <functional>
#include <optional>
#include <string>
#include <string_view>
#include <type_traits>
#include <vector>
 
#include "cli/action.hh"
#include "cli/argument_base.hh"
#include "cli/argument_validation.hh"
#include "cli/meta.hh"
#include "cli/relation.hh"
#include "cli/string_literal.hh"
 
namespace cli {

template <class T>
concept ArgumentSpec = requires {
  requires detail::members_are_derived_from_valid_cli_class<T>();
  requires detail::options_have_unique_long_name<T>();
  requires detail::options_have_unique_short_name<T>();
  requires detail::commands_have_unique_long_name<T>();
  requires detail::positionals_have_variadic_at_end<T>();
  requires detail::relations_are_well_formed<T>();
};
 
template <ArgumentSpec T>
struct Parser;

template <class T>
struct ArgParameter {
  std::string_view help{};  
  Presence presence{Presence::optional};  
  std::optional<T>
      default_value{};  
  std::function<void(const T&)>
      on_parse{};          
  std::string_view env{};  
  bool hidden{};  
  std::string_view
      deprecated{};  
};
 
namespace detail {
 
template <StringLiteral Name, char ShortName, Nargs N, Action A>
  requires requires {
    detail::is_valid_long_option_name<Name>();
    detail::is_valid_short_option_name(ShortName);
    0 <= N.min;
    -1 <= N.max;
    (N.max == -1 || N.min <= N.max);
  }
struct ArgImpl : public OptionTag {
  using value_type =
      typename std::remove_cvref_t<decltype(std::get<1>(A.validate()))>::type;
  ArgImpl() : ArgImpl(ArgParameter<value_type>{}) {}
  ArgImpl(ArgParameter<value_type> param)
      : param_(std::move(param)),
        value_(param_.default_value.value_or(value_type{})) {}
 
  // Convenience constructor for StoreInto variants (value_type == T*).
  ArgImpl(std::remove_pointer_t<value_type>& ref)
    requires std::is_pointer_v<value_type>
      : value_(&ref) {}
  ArgImpl(std::remove_pointer_t<value_type>& ref, ArgParameter<value_type> param)
    requires std::is_pointer_v<value_type>
      : param_(param), value_(&ref) {}
 
  // Bind to an external variable after construction.
  // Allows: opt.bind(var)  or  opt = &var
  auto bind(std::remove_pointer_t<value_type>& ref) -> ArgImpl&
    requires std::is_pointer_v<value_type>
  {
    value_ = &ref;
    return *this;
  }
  auto operator=(std::remove_pointer_t<value_type>* ptr) -> ArgImpl&
    requires std::is_pointer_v<value_type>
  {
    value_ = ptr;
    return *this;
  }
 
  static constexpr auto name = Name;
  static constexpr auto short_name = ShortName;
  static constexpr auto nargs = N;
 
  [[nodiscard]] auto value() const -> const value_type& { return value_; }
  [[nodiscard]] auto value() -> value_type& { return value_; }
  [[nodiscard]] auto provided() const -> bool { return provided_; }
  [[nodiscard]] auto occurrences() const -> std::size_t {
    return occurrence_count_;
  }
  [[nodiscard]] explicit operator bool() const { return value_present_; }
  [[nodiscard]] auto operator*() -> value_type& { return value_; }
  [[nodiscard]] auto operator*() const -> const value_type& { return value_; }
  [[nodiscard]] auto operator->() -> value_type* { return &value_; }
  [[nodiscard]] auto operator->() const -> const value_type* { return &value_; }
 
  template <class U>
  [[nodiscard]] auto value_or(U&& fallback) const -> value_type {
    if (value_present_) return value_;
    return static_cast<value_type>(std::forward<U>(fallback));
  }
 
  [[nodiscard]] explicit operator std::optional<value_type>() const {
    if (value_present_) return value_;
    return std::nullopt;
  }
 
  [[nodiscard]] auto help_text() const -> const std::string_view {
    return param_.help;
  }
  [[nodiscard]] auto hidden() const -> bool { return param_.hidden; }
  [[nodiscard]] auto deprecated() const -> std::string_view {
    return param_.deprecated;
  }
  [[nodiscard]] auto presence() const -> Presence { return param_.presence; }
  [[nodiscard]] auto env() const -> std::string_view { return param_.env; }
  [[nodiscard]] auto default_value() const -> const std::optional<value_type>& {
    return param_.default_value;
  }
 
 protected:
  static constexpr bool entry_is_optional =
      std::remove_cvref_t<decltype(A)>::entry_is_optional;
 
  // Called once when the option token is seen (before processing its values).
  auto notify_option_seen() -> void { ++occurrence_count_; }
 
  // Called once per value token associated with this option.
  auto invoke_action(std::optional<std::string_view> text, std::size_t arg_index,
                     std::size_t occurrence_nargs, std::size_t value_index,
                     bool mark_provided = true) -> ActionResult<void> {
    if (mark_provided) provided_ = true;
    ActionCtx<value_type> ctx{
        .index = arg_index,
        .occurrences = occurrence_count_,
        .nargs = occurrence_nargs,
        .value_index = value_index,
        .total_values = total_values_,
        .arg = std::ref(value_),
    };
    if (text.has_value()) ++total_values_;
 
    auto invoke_result = [&ctx, &text]() -> auto {
      if constexpr (entry_is_optional) {
        return decltype(A)::invoke(
            ctx, ActionResult<std::optional<std::string_view>>::ok(text));
      } else {
        return decltype(A)::invoke(
            ctx, ActionResult<std::string_view>::ok(text.value_or("")));
      }
    }();
    if (invoke_result.has_error()) {
      return ActionResult<void>::fail(std::move(invoke_result.error));
    }
    if (invoke_result.has_value()) value_present_ = true;
    return ActionResult<void>::ok();
  }
 
  // Called once after all value tokens for one option occurrence are processed.
  auto on_parse() -> void {
    if (param_.on_parse) param_.on_parse(value_);
  }
 
  [[nodiscard]] auto get_param() const -> const ArgParameter<value_type>& {
    return param_;
  }
 
  template <ArgumentSpec>
  friend struct ::cli::Parser;
 
 private:
  std::size_t total_values_{};  // total values across all occurrences
  ArgParameter<value_type> param_;
  value_type value_{};
  std::size_t occurrence_count_{};  // times the option token appeared
  bool provided_{};
  bool value_present_{param_.default_value.has_value()};
};
 
template <auto A>
concept ActionValue = requires { std::remove_cvref_t<decltype(A)>::validate(); };
 
template <auto... Args>
struct ArgAlias {
  static_assert(
      sizeof...(Args) && !sizeof...(Args),
      "Unsupported Arg<> parameter combination.\n"
      "Supported forms (after the Name parameter):\n"
      "  Arg<Name, Action>\n"
      "  Arg<Name, Action, Nargs>\n"
      "  Arg<Name, ShortName, Action>\n"
      "  Arg<Name, ShortName, Action, Nargs>\n"
      "Consider using Flag, Option, or ListOption for common argument kinds.");
};
 
template <StringLiteral Name, auto A>
  requires ActionValue<A>
struct ArgAlias<Name, A> {
  using type = ArgImpl<Name, '\0', nargs::one, A>;
};
 
template <StringLiteral Name, auto A, auto N>
  requires(ActionValue<A> &&
           std::same_as<std::remove_cvref_t<decltype(N)>, Nargs>)
struct ArgAlias<Name, A, N> {
  using type = ArgImpl<Name, '\0', N, A>;
};
 
template <StringLiteral Name, char ShortName, auto A>
  requires ActionValue<A>
struct ArgAlias<Name, ShortName, A> {
  using type = ArgImpl<Name, ShortName, nargs::one, A>;
};
 
template <StringLiteral Name, char ShortName, auto A, auto N>
  requires(ActionValue<A> &&
           std::same_as<std::remove_cvref_t<decltype(N)>, Nargs>)
struct ArgAlias<Name, ShortName, A, N> {
  using type = ArgImpl<Name, ShortName, N, A>;
};
 
}  // namespace detail
 
template <Nargs N, Action A>
  requires requires {
    0 <= N.min;
    -1 <= N.max;
    (N.max == -1 || N.min <= N.max);
  }
struct PositionalImpl : public PositionalTag {
  using value_type =
      typename std::remove_cvref_t<decltype(std::get<1>(A.validate()))>::type;
 
  PositionalImpl() : PositionalImpl(ArgParameter<value_type>{}) {}
  PositionalImpl(ArgParameter<value_type> param)
      : value_(param.default_value.value_or(value_type{})),
        param_(std::move(param)) {}
 
  static constexpr auto nargs = N;
 
  // Called once after all tokens for this positional are consumed.
  auto on_parse() -> void {
    if (param_.on_parse) param_.on_parse(value_);
  }
 
  [[nodiscard]] auto value() const -> const value_type& { return value_; }
  [[nodiscard]] auto value() -> value_type& { return value_; }
  [[nodiscard]] auto provided() const -> bool { return provided_; }
  [[nodiscard]] auto occurrences() const -> std::size_t {
    return occurrence_count_;
  }
  [[nodiscard]] explicit operator bool() const { return value_present_; }
  [[nodiscard]] auto operator*() -> value_type& { return value_; }
  [[nodiscard]] auto operator*() const -> const value_type& { return value_; }
  [[nodiscard]] auto operator->() -> value_type* { return &value_; }
  [[nodiscard]] auto operator->() const -> const value_type* { return &value_; }
 
  template <class U>
  [[nodiscard]] auto value_or(U&& fallback) const -> value_type {
    if (value_present_) return value_;
    return static_cast<value_type>(std::forward<U>(fallback));
  }
 
  [[nodiscard]] explicit operator std::optional<value_type>() const {
    if (value_present_) return value_;
    return std::nullopt;
  }
 
  [[nodiscard]] auto help_text() const -> const std::string_view {
    return param_.help;
  }
  [[nodiscard]] auto hidden() const -> bool { return param_.hidden; }
  [[nodiscard]] auto deprecated() const -> std::string_view {
    return param_.deprecated;
  }
  [[nodiscard]] auto presence() const -> Presence { return param_.presence; }
  [[nodiscard]] auto env() const -> std::string_view { return param_.env; }
  [[nodiscard]] auto default_value() const -> const std::optional<value_type>& {
    return param_.default_value;
  }
 
 protected:
  [[nodiscard]] auto get_param() const -> const ArgParameter<value_type>& {
    return param_;
  }
 
  static constexpr bool entry_is_optional =
      std::remove_cvref_t<decltype(A)>::entry_is_optional;
 
  // Called once per value token for this positional.
  auto invoke_action(std::string_view text, std::size_t arg_index,
                     std::size_t occurrence_nargs = 1,
                     std::size_t value_index = 0) -> ActionResult<void> {
    provided_ = true;
    ++occurrence_count_;
    ActionCtx<value_type> ctx{
        .index = arg_index,
        .occurrences = occurrence_count_,
        .nargs = occurrence_nargs,
        .value_index = value_index,
        .total_values = total_values_,
        .arg = std::ref(value_),
    };
    ++total_values_;
    auto result =
        decltype(A)::invoke(ctx, ActionResult<std::string_view>::ok(text));
    if (result.has_error()) {
      return ActionResult<void>::fail(std::move(result.error));
    }
    if (result.has_value()) value_present_ = true;
    return ActionResult<void>::ok();
  }
 
 private:
  template <ArgumentSpec>
  friend struct Parser;
 
  value_type value_{};
  ArgParameter<value_type> param_;
  std::size_t occurrence_count_{};  // times a value was provided
  std::size_t total_values_{};      // total values across all invocations
  bool provided_{};
  bool value_present_{param_.default_value.has_value()};
};

struct Description : DescriptionTag {
  std::string_view text{};
  constexpr Description() = default;
  template <std::size_t N>
  // NOLINTNEXTLINE(cppcoreguidelines-avoid-c-arrays, modernize-avoid-c-arrays)
  constexpr Description(const char (&s)[N]) : text(s, N - 1) {}
  constexpr Description(std::string_view) = delete;
  constexpr operator std::string_view() const { return text; }
};

struct CommandParameter {
  std::string_view
      help{};     
  bool hidden{};  
  std::string_view
      deprecated{};  
};

template <StringLiteral Name, ArgumentSpec T>
  requires requires { detail::is_valid_command_name<Name>(); }
struct Command : public T, public CommandTag {
  using T::T;
  using argument_type = T;
 
  Command() = default;
  Command(CommandParameter param)
      : help_(param.help),
        hidden_(param.hidden),
        deprecated_(param.deprecated) {}
  static constexpr auto name = Name;
  static constexpr auto command_name() -> std::string_view {
    return Name.view();
  }
  [[nodiscard]] auto provided() const -> bool { return provided_; }
  [[nodiscard]] auto help_text() const -> std::string_view { return help_; }
  [[nodiscard]] auto hidden() const -> bool { return hidden_; }
  [[nodiscard]] auto deprecated() const -> std::string_view {
    return deprecated_;
  }
  auto mark_provided() -> void { provided_ = true; }
 
 private:
  std::string_view help_{};
  bool hidden_{};
  std::string_view deprecated_{};
  bool provided_{};
};
 
namespace detail {
 
template <class T>
struct ActionFor;
 
template <>
struct ActionFor<std::string> {
  inline static constexpr auto set_once = conversion::string | pack::set_once;
  inline static constexpr auto push = conversion::string | pack::push;
  inline static constexpr auto write_to =
      conversion::string | pack::write_to<std::string>;
};
 
template <>
struct ActionFor<bool> {
  inline static constexpr auto set_once = conversion::boolean | pack::set_once;
  inline static constexpr auto push = conversion::boolean | pack::push;
  inline static constexpr auto write_to =
      conversion::boolean | pack::write_to<bool>;
};
 
template <>
struct ActionFor<std::filesystem::path> {
  inline static constexpr auto set_once = conversion::path | pack::set_once;
  inline static constexpr auto push = conversion::path | pack::push;
  inline static constexpr auto write_to =
      conversion::path | pack::write_to<std::filesystem::path>;
};
 
template <std::integral T>
struct ActionFor<T> {
  inline static constexpr auto set_once =
      conversion::integer<T> | pack::set_once;
  inline static constexpr auto push = conversion::integer<T> | pack::push;
  inline static constexpr auto write_to =
      conversion::integer<T> | pack::write_to<T>;
};
 
template <std::floating_point T>
struct ActionFor<T> {
  inline static constexpr auto set_once =
      conversion::floating<T> | pack::set_once;
  inline static constexpr auto push = conversion::floating<T> | pack::push;
  inline static constexpr auto write_to =
      conversion::floating<T> | pack::write_to<T>;
};
 
template <class T, Nargs N>
struct PositionalActionFor {
  inline static constexpr auto value = []() -> auto {
    if constexpr (N.max == 1) {
      return ActionFor<T>::set_once;
    } else {
      return ActionFor<T>::push;
    }
  }();
};
 
}  // namespace detail
 
// ── Core public API ───────────────────────────────────────────────────────────

template <StringLiteral Name, auto... Args>
using Arg = typename detail::ArgAlias<Name, Args...>::type;

template <StringLiteral Name, char ShortName = '\0'>
using Flag = Arg<Name, ShortName, pack::set_true, nargs::none>;

template <class T, StringLiteral Name, char ShortName = '\0'>
using BoundOption = Arg<Name, ShortName, detail::ActionFor<T>::write_to>;

template <StringLiteral Name, char ShortName = '\0'>
using BoundStringOption = BoundOption<std::string, Name, ShortName>;

template <StringLiteral Name, char ShortName = '\0'>
using BoundIntOption = BoundOption<int, Name, ShortName>;

template <StringLiteral Name, char ShortName = '\0'>
using BoundDoubleOption = BoundOption<double, Name, ShortName>;

template <StringLiteral Name, char ShortName = '\0'>
using BoundPathOption = BoundOption<std::filesystem::path, Name, ShortName>;

template <StringLiteral Name = "help", char ShortName = 'h'>
using Help =
    Arg<Name, ShortName, action::print_help | action::exit_success, nargs::none>;

template <class T, StringLiteral Name, char ShortName = '\0'>
using Option = Arg<Name, ShortName, detail::ActionFor<T>::set_once>;

template <class T, StringLiteral Name, char ShortName = '\0',
          Nargs N = nargs::one_or_more>
using ListOption = Arg<Name, ShortName, detail::ActionFor<T>::push, N>;

template <class T, Nargs N = nargs::one>
using Positional = PositionalImpl<N, detail::PositionalActionFor<T, N>::value>;
 
// ── Convenience aliases for common types ─────────────────────────────────────

template <StringLiteral Name, char ShortName = '\0'>
using StringOption = Option<std::string, Name, ShortName>;

template <StringLiteral Name, char ShortName = '\0'>
using IntOption = Option<int, Name, ShortName>;

template <StringLiteral Name, char ShortName = '\0'>
using DoubleOption = Option<double, Name, ShortName>;

template <StringLiteral Name, char ShortName = '\0'>
using PathOption = Option<std::filesystem::path, Name, ShortName>;
 
}  // namespace cli