parser.hh

Go to the documentation of this file.

#pragma once
 
// #include <expected>
#include <array>
#include <cstdint>
#include <cstdio>
#include <cstdlib>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <tuple>
#include <type_traits>
#include <utility>
#include <vector>
 
#ifdef _WIN32
#define NOMINMAX
#define WIN32_LEAN_AND_MEAN
#include <windows.h>
#endif
 
#include "cli/argument.hh"
#include "cli/constraint.hh"
#include "cli/error.hh"
#include "cli/help.hh"
 
#ifndef CLI20_TOKEN_STACK_CAPACITY
#define CLI20_TOKEN_STACK_CAPACITY 32
#endif
 
static_assert(CLI20_TOKEN_STACK_CAPACITY > 0,
              "CLI20_TOKEN_STACK_CAPACITY must be greater than zero");
 
namespace cli {

inline constexpr std::size_t token_stack_capacity = CLI20_TOKEN_STACK_CAPACITY;
 
namespace detail {
 
inline auto write_message(FILE* file, std::string_view message) -> void {
  if (file == nullptr || message.empty()) return;
  (void)std::fwrite(message.data(), 1, message.size(), file);
  (void)std::fwrite("\n", 1, 1, file);
}
 
inline auto value_count_message(int required_count, int provided)
    -> std::string {
  return "option requires at least " + std::to_string(required_count) +
         " value(s), but " + std::to_string(provided) + " provided";
}
 
inline auto inline_value_count_message(int required_count) -> std::string {
  return "option requires at least " + std::to_string(required_count) +
         " value(s), but inline separator provides only 1";
}
 
}  // namespace detail
 
#ifdef _WIN32
namespace detail {
inline auto wide_to_utf8(const wchar_t* wide) -> std::string {
  if (!wide) return {};
  constexpr DWORD flags = WC_ERR_INVALID_CHARS;
  int len = WideCharToMultiByte(CP_UTF8, flags, wide, -1, nullptr, 0, nullptr,
                                nullptr);
  if (len <= 1) return {};
  std::string result(static_cast<std::size_t>(len) - 1, '\0');
  const int written = WideCharToMultiByte(CP_UTF8, flags, wide, -1,
                                          result.data(), len, nullptr, nullptr);
  if (written != len) return {};
  return result;
}
}  // namespace detail

struct Utf8Argv {
  std::vector<std::string> storage;
  std::vector<char*> pointers;
 
  [[nodiscard]] auto size() const -> int {
    return static_cast<int>(pointers.size());
  }
 
  [[nodiscard]] auto data() -> char** { return pointers.data(); }
};

inline auto utf16_to_utf8(int argc, wchar_t* argv[]) -> Utf8Argv {
  Utf8Argv result;
  result.storage.reserve(static_cast<std::size_t>(argc));
  result.pointers.reserve(static_cast<std::size_t>(argc));
  for (int i = 0; i < argc; ++i) {
    result.storage.emplace_back(detail::wide_to_utf8(argv[i]));
  }
  for (std::string& arg : result.storage) {
    result.pointers.push_back(arg.data());
  }
  return result;
}
#endif

enum class TokenType : uint8_t {
  option,
  value,
  positional,
  command,
};
 
static constexpr std::uint8_t kNoPrefix = 0xff;
static constexpr std::uint8_t kShortPrefixBit = 0x80;
static constexpr std::uint8_t kPrefixIndexMask = 0x7f;
 
static constexpr auto no_prefix() -> std::uint8_t { return kNoPrefix; }
 
static constexpr auto short_prefix() -> std::uint8_t { return kShortPrefixBit; }
 
static constexpr auto long_prefix(std::uint8_t i) -> std::uint8_t {
  return i & kPrefixIndexMask;
}
 
static constexpr auto has_prefix(std::uint8_t p) -> bool {
  return p != kNoPrefix;
}
 
static constexpr auto is_short_prefix(std::uint8_t p) -> bool {
  return p != kNoPrefix && (p & kShortPrefixBit);
}

struct Token {
  std::string_view text;  
  std::size_t position;   
  std::uint8_t prefix;  // 0xff = none, high bit = short prefix, low 7bit = long
                        // prefix index
  TokenType type;       
};

struct TokenizeResult {
  template <class T, std::size_t N>
 
  struct SmallVector {
    std::array<T, N> stack{};
    std::vector<T> heap;
    std::size_t size_value{};
 
    auto push_back(T value) -> void {
      if (size_value < N && heap.empty()) {
        stack[size_value++] = std::move(value);
        return;
      }
 
      if (heap.empty()) {
        heap.reserve(N * 2);
        for (std::size_t i = 0; i < size_value; ++i) {
          heap.push_back(std::move(stack[i]));
        }
      }
 
      heap.push_back(std::move(value));
      ++size_value;
    }
 
    [[nodiscard]] auto size() const -> std::size_t { return size_value; }
    [[nodiscard]] auto empty() const -> bool { return size_value == 0; }
 
    auto operator[](std::size_t i) -> T& {
      return heap.empty() ? stack[i] : heap[i];
    }
 
    auto operator[](std::size_t i) const -> const T& {
      return heap.empty() ? stack[i] : heap[i];
    }
 
    [[nodiscard]] auto begin() const {
      return heap.empty() ? stack.data() : heap.data();
    }
 
    [[nodiscard]] auto end() const { return begin() + size_value; }
 
    [[nodiscard]] auto data() const {
      return heap.empty() ? stack.data() : heap.data();
    }
  };
 
  SmallVector<Token, token_stack_capacity> tokens;
  ParseError error{};

  [[nodiscard]]
  constexpr explicit operator bool() const noexcept {
    return !error.has_error();
  }

  [[nodiscard]]
  constexpr auto has_value() const noexcept -> bool {
    return !error.has_error();
  }

  [[nodiscard]]
  constexpr auto has_error() const noexcept -> bool {
    return error.has_error();
  }

  auto fail(ErrorCode code, std::size_t pos, std::string subject,
            std::string detail = {}) -> TokenizeResult& {
    error = ParseError{
        .code = code,
        .kind = ErrorKind::parse,
        .position = static_cast<int>(pos),
        .subject = std::move(subject),
        .detail = std::move(detail),
    };
    return *this;
  }
};

struct TokenizerConfig {
  static constexpr std::size_t max_option_prefixes = 4;
 
 private:
  std::array<std::string_view, max_option_prefixes> option_prefixes_{"--"};
  std::uint8_t option_prefix_count_{1};
 
  std::string_view short_option_prefix_{"-"};
  std::string_view end_of_options_separator_{"--"};
  char inline_value_separator_{'='};
 
 public:
  constexpr TokenizerConfig() = default;
 
  [[nodiscard]] constexpr auto option_prefixes() const
      -> std::span<const std::string_view> {
    return {option_prefixes_.data(), option_prefix_count_};
  }
 
  [[nodiscard]] constexpr auto short_option_prefix() const -> std::string_view {
    return short_option_prefix_;
  }
 
  [[nodiscard]] constexpr auto end_of_options_separator() const
      -> std::string_view {
    return end_of_options_separator_;
  }
 
  [[nodiscard]] constexpr auto inline_value_separator() const -> char {
    return inline_value_separator_;
  }
 
  template <StringLiteral... Prefixes>
  constexpr auto set_option_prefixes() -> void {
    static_assert(sizeof...(Prefixes) > 0,
                  "TokenizerConfig needs at least one option prefix");
    static_assert(sizeof...(Prefixes) <= max_option_prefixes,
                  "Too many option prefixes for TokenizerConfig");
    option_prefix_count_ = 0;
    ((option_prefixes_[option_prefix_count_++] = Prefixes.view()), ...);
  }
 
  template <StringLiteral... Prefixes>
  [[nodiscard]] constexpr auto with_option_prefixes() const -> TokenizerConfig {
    auto cfg = *this;
    cfg.template set_option_prefixes<Prefixes...>();
    return cfg;
  }
 
  template <StringLiteral Prefix>
  [[nodiscard]] constexpr auto with_short_option_prefix() const
      -> TokenizerConfig {
    auto cfg = *this;
    cfg.short_option_prefix_ = Prefix.view();
    return cfg;
  }
 
  template <StringLiteral Separator>
  [[nodiscard]] constexpr auto with_end_of_options_separator() const
      -> TokenizerConfig {
    auto cfg = *this;
    cfg.end_of_options_separator_ = Separator.view();
    return cfg;
  }
 
  [[nodiscard]] constexpr auto with_inline_value_separator(char separator) const
      -> TokenizerConfig {
    auto cfg = *this;
    cfg.inline_value_separator_ = separator;
    return cfg;
  }
};

inline auto token_prefix_view(const Token& tok, const TokenizerConfig& cfg)
    -> std::string_view {
  if (tok.prefix == kNoPrefix) return {};
  if (tok.prefix & kShortPrefixBit) return cfg.short_option_prefix();
  return cfg.option_prefixes()[tok.prefix & kPrefixIndexMask];
}

template <class OptionLookup, class CommandLookup>
inline auto tokenize(std::span<const std::string_view> args,
                     OptionLookup option_nargs, CommandLookup is_command,
                     const TokenizerConfig& cfg = {}) -> TokenizeResult {
  TokenizeResult result;
 
  // Returns an encoded prefix tag that can be decoded with token_prefix_view().
  const auto find_prefix = [&](std::string_view tok) -> std::uint8_t {
    for (std::uint8_t pi = 0;
         pi < static_cast<uint8_t>(cfg.option_prefixes().size()); ++pi) {
      const auto& p = cfg.option_prefixes()[pi];
      if (tok.size() > p.size() && tok.starts_with(p)) {
        return long_prefix(pi);
      }
    }
 
    if (tok.size() > cfg.short_option_prefix().size() &&
        tok.starts_with(cfg.short_option_prefix())) {
      return short_prefix();
    }
 
    return no_prefix();
  };
 
  const auto prefix_view = [&](std::uint8_t p) -> std::string_view {
    if (p == no_prefix()) return {};
    if (is_short_prefix(p)) return cfg.short_option_prefix();
    return cfg.option_prefixes()[p & kPrefixIndexMask];
  };
 
  const auto push = [&](TokenType type, std::string_view text, std::size_t pos,
                        std::uint8_t prefix = kNoPrefix) -> void {
    result.tokens.push_back({
        .text = text,
        .position = pos,
        .prefix = prefix,
        .type = type,
    });
  };
 
  bool post_separator = false;
  std::size_t i = 0;
 
  while (i < args.size()) {
    const std::string_view tok = args[i];
 
    // ── option parsing terminator ─────────────────────────────────────────
    if (!post_separator && tok == cfg.end_of_options_separator()) {
      post_separator = true;
      ++i;
      continue;
    }
 
    // ── after separator: everything is positional ─────────────────────────
    if (post_separator) {
      push(TokenType::positional, tok, i++);
      continue;
    }
 
    // ── command name ──────────────────────────────────────────────────────
    const auto prefix = find_prefix(tok);
    const auto prefix_sv = prefix_view(prefix);
    if (!has_prefix(prefix) && is_command(tok)) {
      push(TokenType::command, tok, i);
      break;  // args[i+1:] are the sub-command's responsibility
    }
 
    // ── option-looking token ──────────────────────────────────────────────
    if (has_prefix(prefix)) {
      const auto sep = cfg.inline_value_separator();
      const auto eq_pos = tok.find(sep);
      const bool has_inline_val = (eq_pos != std::string_view::npos);
      const std::string_view opt_sv =
          has_inline_val ? tok.substr(0, eq_pos) : tok;
      const auto nargs_opt = option_nargs(opt_sv);
      if (!nargs_opt) {
        // Short cluster (-xvf) or attached value (-ofile): only when the token
        // uses the short prefix and carries more than one character after it.
        const std::string_view body = opt_sv.substr(prefix_sv.size());
        if (is_short_prefix(prefix) && !has_inline_val && body.size() > 1) {
          bool advanced_i = false;
          const std::string_view char_prefix = tok.substr(0, prefix_sv.size());
          std::string char_full{char_prefix};
          char_full.push_back('\0');
          for (std::size_t k = 0; k < body.size(); ++k) {
            const std::string_view char_bare =
                tok.substr(prefix_sv.size() + k, 1);
            char_full.back() = body[k];
            const auto char_nargs_opt = option_nargs(char_full);
            if (!char_nargs_opt) {
              return result.fail(ErrorCode::unknown_option, i, char_full);
            }
            const Nargs nargs = *char_nargs_opt;
            const bool is_flag = (nargs.min == 0 && nargs.max == 0);
            push(TokenType::option, char_bare, i, prefix);
            if (!is_flag) {
              if (k + 1 < body.size()) {
                // First value is attached (rest of body).
                push(TokenType::value, tok.substr(prefix_sv.size() + k + 1), i);
                ++i;
                // Consume additional tokens for nargs > 1.
                int count = 1;
                while (i < args.size()) {
                  const std::string_view next = args[i];
                  if (next == cfg.end_of_options_separator()) break;
                  if (is_command(next)) break;
                  if (nargs.max != -1 && count >= nargs.max) break;
                  if (has_prefix(find_prefix(next))) {
                    const auto next_sep = next.find(sep);
                    const std::string_view next_opt =
                        next_sep != std::string_view::npos
                            ? next.substr(0, next_sep)
                            : next;
                    if (option_nargs(next_opt).has_value()) break;
                    if (count >= 1 || nargs.min == 0) break;
                  }
                  push(TokenType::value, args[i], i);
                  ++i;
                  ++count;
                }
                if (count < nargs.min) {
                  return result.fail(
                      ErrorCode::missing_value, i, char_full,
                      detail::value_count_message(nargs.min, count));
                }
              } else {
                // Consume next token(s) greedily as values
                ++i;
                int count = 0;
                while (i < args.size()) {
                  const std::string_view next = args[i];
                  if (next == cfg.end_of_options_separator()) break;
                  if (is_command(next)) break;
                  if (nargs.max != -1 && count >= nargs.max) break;
                  if (has_prefix(find_prefix(next))) {
                    const auto next_sep = next.find(sep);
                    const std::string_view next_opt =
                        next_sep != std::string_view::npos
                            ? next.substr(0, next_sep)
                            : next;
                    if (option_nargs(next_opt).has_value()) break;
                    if (count >= 1 || nargs.min == 0) break;
                  }
                  push(TokenType::value, args[i], i);
                  ++i;
                  ++count;
                }
                if (count < nargs.min) {
                  return result.fail(
                      ErrorCode::missing_value, i, char_full,
                      detail::value_count_message(nargs.min, count));
                }
              }
              advanced_i = true;
              break;
            }
          }
          if (!advanced_i) ++i;
          continue;
        }
        return result.fail(ErrorCode::unknown_option, i, std::string(opt_sv));
      }
 
      const Nargs& nargs = *nargs_opt;
      const bool is_flag = (nargs.min == 0 && nargs.max == 0);
 
      // Store bare name (without prefix) in text; matched_prefix holds the
      // prefix.
 
      push(TokenType::option, opt_sv.substr(prefix_sv.size()), i, prefix);
 
      if (has_inline_val) {
        if (is_flag) {
          return result.fail(ErrorCode::invalid_value, i, std::string(opt_sv),
                             "flag does not accept a value");
        }
        if (nargs.min > 1) {
          return result.fail(ErrorCode::missing_value, i, std::string(opt_sv),
                             detail::inline_value_count_message(nargs.min));
        }
        push(TokenType::value, tok.substr(eq_pos + 1), i);
        ++i;
        continue;
      }
 
      // prefix-opt form: advance, then greedily consume value tokens
      ++i;
 
      if (is_flag) continue;
 
      int count = 0;
      while (i < args.size()) {
        const std::string_view next = args[i];
 
        if (next == cfg.end_of_options_separator()) break;
        if (is_command(next)) break;
        if (nargs.max != -1 && count >= nargs.max) break;
 
        if (has_prefix(find_prefix(next))) {
          const auto next_sep = next.find(sep);
          const std::string_view next_opt = next_sep != std::string_view::npos
                                                ? next.substr(0, next_sep)
                                                : next;
          if (option_nargs(next_opt).has_value()) break;
 
          // Unknown option-looking: consume only as first value when min > 0
          if (count >= 1 || nargs.min == 0) break;
        }
 
        push(TokenType::value, args[i], i);
        ++i;
        ++count;
      }
 
      if (count < nargs.min) {
        return result.fail(ErrorCode::missing_value, i, std::string(opt_sv),
                           detail::value_count_message(nargs.min, count));
      }
      continue;
    }
 
    // ── bare token → positional ───────────────────────────────────────────
    push(TokenType::positional, tok, i++);
  }
 
  return result;
}

template <class T>
struct ParseResult {
  T value{};  
  ParseError
      error{};  

  [[nodiscard]]
  constexpr explicit operator bool() const noexcept {
    return !error.has_error();
  }

  [[nodiscard]]
  constexpr auto has_value() const noexcept -> bool {
    return !error.has_error();
  }

  [[nodiscard]]
  constexpr auto has_error() const noexcept -> bool {
    return error.has_error();
  }

  template <class U>
  [[nodiscard]]
  static constexpr auto ok(U&& value) -> ParseResult<T> {
    return {
        .value = std::forward<U>(value),
        .error = {},
    };
  }

  [[nodiscard]]
  static constexpr auto fail(ParseError error) -> ParseResult<T> {
    return {
        .value = {},
        .error = std::move(error),
    };
  }
};

template <ArgumentSpec T>
struct Parser {
  template <ArgumentSpec>
  friend struct Parser;

  // NOLINTNEXTLINE(cppcoreguidelines-avoid-c-arrays, modernize-avoid-c-arrays)
  auto parse(int argc, char* argv[]) -> ParseResult<T> {
    std::vector<std::string_view> args;
    args.reserve(static_cast<std::size_t>(argc));
    for (int i = 0; i < argc; ++i) {
      args.emplace_back(argv[i]);
    }
    if (argc > 0) {
      set_program_name(argv[0]);
    }
    return this->parse(std::span<const std::string_view>(args), 1);
  }

  // NOLINTNEXTLINE(cppcoreguidelines-avoid-c-arrays, modernize-avoid-c-arrays)
  auto parse(T initial, int argc, char* argv[]) -> ParseResult<T> {
    std::vector<std::string_view> args;
    args.reserve(static_cast<std::size_t>(argc));
    for (int i = 0; i < argc; ++i) {
      args.emplace_back(argv[i]);
    }
    if (argc > 0) {
      set_program_name(argv[0]);
    }
    return this->parse(std::move(initial),
                       std::span<const std::string_view>(args), 1);
  }

  auto parse(std::span<const std::string_view> args, std::size_t first_index = 0)
      -> ParseResult<T> {
    ParseResult<T> result;
    parse_body(result, args, first_index);
    return result;
  }

  auto parse(std::span<const std::string_view> args,
             std::string_view program_name, std::size_t first_index = 0)
      -> ParseResult<T> {
    set_program_name(std::string(program_name));
    ParseResult<T> result;
    parse_body(result, args, first_index);
    return result;
  }

  auto parse(T initial, std::span<const std::string_view> args,
             std::size_t first_index = 0) -> ParseResult<T> {
    ParseResult<T> result;
    result.value = std::move(initial);
    parse_body(result, args, first_index);
    return result;
  }

  auto parse(T initial, std::span<const std::string_view> args,
             std::string_view program_name, std::size_t first_index = 0)
      -> ParseResult<T> {
    set_program_name(program_name);
    ParseResult<T> result;
    result.value = std::move(initial);
    parse_body(result, args, first_index);
    return result;
  }

  [[nodiscard]] auto program_name() const -> const std::string& {
    return program_name_;
  }

  auto set_program_name(std::string name) -> void {
    program_name_ = std::move(name);
  }
 
 private:
  TokenizerConfig cfg_;
  std::string program_name_ = "program";
 
  static constexpr std::size_t field_count = std::tuple_size_v<
      std::remove_reference_t<decltype(as_tuple(std::declval<T&>()))>>;
 
  auto parse_body(ParseResult<T>& result, std::span<const std::string_view> args,
                  std::size_t first_index) -> void {
    auto lookup = get_option_spec_map(result.value);
 
    auto tokenized = tokenize(
        args.subspan(std::min(first_index, args.size())),
        [&](std::string_view opt) -> auto { return lookup.option_nargs(opt); },
        [&](std::string_view name) -> auto { return lookup.is_command(name); },
        cfg_);
    if (tokenized.has_error()) {
      if (tokenized.error.has_position()) {
        tokenized.error.position += static_cast<int>(first_index);
      }
      result.error = std::move(tokenized.error);
      return;
    }
 
    const auto& tokens = tokenized.tokens;
    std::size_t pos_idx = 0, pos_cnt = 0;
 
    for (std::size_t i = 0; i < tokens.size();) {
      const Token& tok = tokens[i];
 
      if (tok.type == TokenType::option) {
        std::size_t j = i + 1;
        while (j < tokens.size() && tokens[j].type == TokenType::value) ++j;
        auto err =
            dispatch_option(result.value, token_prefix_view(tok, cfg_), tok.text,
                            std::span(tokens).subspan(i + 1, j - i - 1),
                            first_index, tok.position);
        if (err.has_error()) {
          result.error = finalize_special_error(std::move(err.error));
          return;
        }
        i = j;
 
      } else if (tok.type == TokenType::positional) {
        auto err = dispatch_positional(result.value, pos_idx, pos_cnt, tok.text,
                                       tok.position + first_index);
        if (err.has_error()) {
          result.error = finalize_special_error(std::move(err.error));
          return;
        }
        ++i;
 
      } else if (tok.type == TokenType::command) {
        auto err = dispatch_command(result.value, tok.text, args,
                                    tok.position + first_index + 1);
        if (err.has_error()) {
          result.error = finalize_special_error(std::move(err.error));
          return;
        }
        break;
 
      } else {
        ++i;
      }
    }
 
    // Fire on_parse callbacks for positionals once, after all tokens are
    // consumed.
    for_each_field(result.value, [](auto& f) -> auto {
      using F = std::remove_cvref_t<decltype(f)>;
      if constexpr (std::derived_from<F, PositionalTag>) {
        if (f.provided()) f.on_parse();
      }
    });
 
    if (auto err = apply_env_fallback(result.value); err.has_error()) {
      result.error = std::move(err.error);
      return;
    }
 
    if (auto err = validate_required(result.value); err.has_error()) {
      result.error = std::move(err.error);
      return;
    }
 
    if (auto err = validate_relations(result.value); err.has_error()) {
      result.error = std::move(err.error);
      return;
    }
 
    if constexpr (requires(T& t) {
                    { t.constraints() } -> std::same_as<ConstraintResult>;
                  }) {
      if (auto cr = result.value.constraints(); !cr.ok()) {
        result.error = std::move(*cr.error);
      }
    }
  }
 
 public:
  auto format_help(ColorMode color_mode = ColorMode::detect,
                   HelpPalette palette = default_help_palette) -> std::string {
    return cli::format_help<T>(scratch_, program_name_, color_mode, false,
                               palette);
  }

  auto format_help(RecurseHelpTag) -> std::string {
    return format_help(ColorMode::detect, recurse_help);
  }
 
  auto format_help(HelpPalette palette) -> std::string {
    return format_help(ColorMode::detect, palette);
  }

  auto format_help(ColorMode color_mode, RecurseHelpTag) -> std::string {
    return cli::format_help<T>(scratch_, program_name_, color_mode, true);
  }
 
  auto format_help(ColorMode color_mode, HelpPalette palette, RecurseHelpTag)
      -> std::string {
    return cli::format_help<T>(scratch_, program_name_, color_mode, true,
                               palette);
  }
 
 private:
  T scratch_{};
 
  // Iterate every field of val, calling fn(field) for each.
  template <class Fn>
  static constexpr void for_each_field(T& val, Fn fn) {
    auto&& tup = as_tuple(val);
    [&]<std::size_t... I>(std::index_sequence<I...>)
        -> auto {
      (fn(std::get<I>(tup)), ...);
    }(std::make_index_sequence<
            std::tuple_size_v<std::remove_reference_t<decltype(tup)>>>{});
  }
 
  template <class Fn>
  static constexpr void for_each_field(const T& val, Fn fn) {
    auto&& tup = as_tuple(val);
    [&]<std::size_t... I>(std::index_sequence<I...>)
        -> auto {
      (fn(std::get<I>(tup)), ...);
    }(std::make_index_sequence<
            std::tuple_size_v<std::remove_reference_t<decltype(tup)>>>{});
  }
 
  // Build a flat lookup table once per parse so tokenization does not reflect
  // over every field for every argv token.
  struct Lookup {
    struct OptionEntry {
      std::string_view prefix;
      std::string_view name;
      char short_name{};
      Nargs nargs{};
      bool is_short{};
    };
 
    struct CommandEntry {
      std::string_view name;
    };
 
    std::array<OptionEntry,
               field_count*(TokenizerConfig::max_option_prefixes + 1)>
        options{};
    std::array<CommandEntry, field_count> commands{};
    std::size_t option_count{};
    std::size_t command_count{};
 
    auto add_long_option(std::string_view prefix, std::string_view name,
                         Nargs nargs) -> void {
      options[option_count++] = OptionEntry{
          .prefix = prefix,
          .name = name,
          .short_name = '\0',
          .nargs = nargs,
          .is_short = false,
      };
    }
 
    auto add_short_option(std::string_view prefix, char short_name, Nargs nargs)
        -> void {
      options[option_count++] = OptionEntry{
          .prefix = prefix,
          .name = {},
          .short_name = short_name,
          .nargs = nargs,
          .is_short = true,
      };
    }
 
    auto add_command(std::string_view name) -> void {
      commands[command_count++] = CommandEntry{.name = name};
    }
 
    [[nodiscard]] auto option_nargs(std::string_view opt) const
        -> std::optional<Nargs> {
      for (std::size_t i = 0; i < option_count; ++i) {
        const auto& entry = options[i];
        if (!opt.starts_with(entry.prefix)) {
          continue;
        }
        const auto rest = opt.substr(entry.prefix.size());
        if (entry.is_short) {
          if (rest.size() == 1 && rest.front() == entry.short_name) {
            return entry.nargs;
          }
        } else if (rest == entry.name) {
          return entry.nargs;
        }
      }
      return std::nullopt;
    }
 
    [[nodiscard]] auto is_command(std::string_view name) const -> bool {
      for (std::size_t i = 0; i < command_count; ++i) {
        if (commands[i].name == name) return true;
      }
      return false;
    }
  };
 
  auto get_option_spec_map(const T& val) const -> Lookup {
    Lookup lookup{};
    for_each_field(val, [&](const auto& f) -> auto {
      using F = std::remove_cvref_t<decltype(f)>;
      if constexpr (std::derived_from<F, OptionTag>) {
        for (const auto& p : cfg_.option_prefixes()) {
          lookup.add_long_option(p, F::name.view(), F::nargs);
        }
        if constexpr (F::short_name != '\0') {
          lookup.add_short_option(cfg_.short_option_prefix(), F::short_name,
                                  F::nargs);
        }
      } else if constexpr (std::derived_from<F, CommandTag>) {
        lookup.add_command(F::command_name());
      }
    });
    return lookup;
  }
 
  // Find the option field matching (prefix, bare), notify it, and invoke its
  // action on each value token. notify_option_seen() is called once;
  // invoke_action() is called once for flags / missing optional entries, or
  // once per value token otherwise.
  auto dispatch_option(T& val, std::string_view prefix, std::string_view bare,
                       std::span<const Token> vals, std::size_t first_index,
                       std::size_t option_position) -> ActionResult<void> {
    ActionResult<void> res = ActionResult<void>::ok();
    bool found = false;
    for_each_field(val, [&](auto& f) -> auto {
      using F = std::remove_cvref_t<decltype(f)>;
      if constexpr (std::derived_from<F, OptionTag>) {
        if (found) {
          return;
        }
        bool match = false;
        for (const auto& p : cfg_.option_prefixes()) {
          if (p == prefix && F::name.view() == bare) {
            match = true;
            break;
          }
        }
        if (!match && F::short_name != '\0' &&
            cfg_.short_option_prefix() == prefix && bare.size() == 1 &&
            bare[0] == F::short_name) {
          match = true;
        }
        if (!match) {
          return;
        }
        found = true;
        f.notify_option_seen();
        if constexpr (F::entry_is_optional) {
          res = f.invoke_action(std::nullopt, option_position + first_index,
                                vals.size(), 0);
        }
        const std::size_t nargs = vals.size();
        for (std::size_t vi = 0; vi < vals.size(); ++vi) {
          if (res.has_error()) {
            break;
          }
          res = f.invoke_action(vals[vi].text, vals[vi].position + first_index,
                                nargs, vi);
        }
        if (!res.has_error()) f.on_parse();
      }
    });
    return res;
  }
 
  // Fill the pos_idx-th positional field with text.  Advances pos_idx/pos_cnt
  // when the current field reaches its nargs.max.
  static auto dispatch_positional(T& val, std::size_t& pos_idx,
                                  std::size_t& pos_cnt, std::string_view text,
                                  std::size_t position) -> ActionResult<void> {
    ActionResult<void> res = ActionResult<void>::ok();
    bool invoked = false;
    std::size_t cur = 0;
    for_each_field(val, [&](auto& f) -> auto {
      using F = std::remove_cvref_t<decltype(f)>;
      if constexpr (std::derived_from<F, PositionalTag>) {
        if (cur++ != pos_idx || invoked) return;
        invoked = true;
        res = f.invoke_action(text, position);
        if (res.has_value()) {
          ++pos_cnt;
          if (F::nargs.max != -1 &&
              pos_cnt >= static_cast<std::size_t>(F::nargs.max)) {
            ++pos_idx;
            pos_cnt = 0;
          }
        }
      }
    });
    if (!invoked)
      return ActionResult<void>::fail(
          ParseError{.code = ErrorCode::unexpected_argument,
                     .kind = ErrorKind::parse,
                     .position = static_cast<int>(position),
                     .subject = std::string(text)});
    return res;
  }
 
  auto dispatch_command(T& val, std::string_view name,
                        std::span<const std::string_view> args,
                        std::size_t first_index) -> ActionResult<void> {
    ActionResult<void> res = ActionResult<void>::ok();
    bool found = false;
    for_each_field(val, [&](auto& f) -> auto {
      using F = std::remove_cvref_t<decltype(f)>;
      if constexpr (std::derived_from<F, CommandTag>) {
        if (found || F::command_name() != name) {
          return;
        }
        found = true;
        f.mark_provided();
        auto sub_parser = Parser<typename F::argument_type>{};
        sub_parser.set_program_name(program_name_ + " " +
                                    std::string(F::command_name()));
        auto sub = sub_parser.parse(args, first_index);
        if (sub.has_error()) {
          res = ActionResult<void>::fail(std::move(sub.error));
        } else {
          static_cast<typename F::argument_type&>(f) = std::move(sub.value);
          f.mark_provided();
        }
      }
    });
    if (!found) {
      return ActionResult<void>::fail(ParseError{
          .code = ErrorCode::unknown_command,
          .kind = ErrorKind::parse,
          .position = static_cast<int>(first_index - 1),
          .subject = std::string(name),
      });
    }
    return res;
  }
 
  static auto validate_required(T& val) -> ActionResult<void> {
    ActionResult<void> res = ActionResult<void>::ok();
    for_each_field(val, [&](auto& f) -> auto {
      using F = std::remove_cvref_t<decltype(f)>;
      if constexpr (std::derived_from<F, OptionTag> ||
                    std::derived_from<F, PositionalTag>) {
        if (res.has_error()) {
          return;
        }
        if (f.get_param().presence == Presence::required &&
            !static_cast<bool>(f)) {
          std::string subject;
          if constexpr (std::derived_from<F, OptionTag>) {
            subject = "--" + std::string(F::name.view());
          } else {
            subject = "<positional>";
          }
          res = ActionResult<void>::fail(ParseError{
              .code = ErrorCode::missing_required,
              .kind = ErrorKind::parse,
              .subject = std::move(subject),
          });
        }
      }
    });
    return res;
  }
 
  static auto relation_name_list(NameList<> names) -> std::string {
    std::string out;
    for (std::size_t i = 0; i < names.size; ++i) {
      if (i != 0) out += ", ";
      out += "--";
      out += names.values[i];
    }
    return out;
  }
 
  static auto relation_group_exists(std::string_view name) -> bool {
    if constexpr (!detail::HasRelations<T>) {
      return false;
    } else {
      bool found = false;
      std::apply(
          [&](auto... rels) -> auto {
            (
                [&]() -> auto {
                  using R = std::remove_cvref_t<decltype(rels)>;
                  if constexpr (std::same_as<R, GroupRelation>) {
                    if (rels.name == name) found = true;
                  }
                }(),
                ...);
          },
          T::relations.items);
      return found;
    }
  }
 
  static auto relation_operand_label(std::string_view operand) -> std::string {
    if (relation_group_exists(operand)) {
      return std::string(operand);
    }
    return "--" + std::string(operand);
  }
 
  static auto relation_operand_present(T& val, std::string_view name) -> bool {
    bool found_field = false;
    bool present = false;
    for_each_field(val, [&](auto& f) -> auto {
      using F = std::remove_cvref_t<decltype(f)>;
      if constexpr (std::derived_from<F, OptionTag> ||
                    std::derived_from<F, CommandTag>) {
        if (!found_field && F::name.view() == name) {
          found_field = true;
          present = f.provided();
        }
      }
    });
    if (found_field) return present;
 
    if constexpr (detail::HasRelations<T>) {
      bool found_group = false;
      bool group_present = false;
      std::apply(
          [&](auto... rels) -> auto {
            (
                [&]() -> auto {
                  using R = std::remove_cvref_t<decltype(rels)>;
                  if constexpr (std::same_as<R, GroupRelation>) {
                    if (!found_group && rels.name == name) {
                      found_group = true;
                      group_present = true;
                      for (auto member : rels.members) {
                        group_present = group_present &&
                                        relation_operand_present(val, member);
                      }
                    }
                  }
                }(),
                ...);
          },
          T::relations.items);
      return group_present;
    }
    return false;
  }
 
  static auto validate_relations(T& val) -> ActionResult<void> {
    if constexpr (!detail::HasRelations<T>) {
      return ActionResult<void>::ok();
    } else {
      ActionResult<void> res = ActionResult<void>::ok();
      std::apply(
          [&](auto... rels) -> auto {
            (
                [&]() -> auto {
                  if (res.has_error()) return;
                  using R = std::remove_cvref_t<decltype(rels)>;
                  if constexpr (std::same_as<R, GroupRelation>) {
                    std::size_t count = 0;
                    for (auto member : rels.members) {
                      if (relation_operand_present(val, member)) ++count;
                    }
                    if (count != 0 && count != rels.members.size) {
                      res = ActionResult<void>::fail(ParseError{
                          .code = ErrorCode::dependency_missing,
                          .kind = ErrorKind::validation,
                          .subject = std::string(rels.name),
                          .detail = "arguments must be provided together: " +
                                    relation_name_list(rels.members),
                      });
                    }
                  } else if constexpr (std::same_as<R, ConflictsRelation>) {
                    if (relation_operand_present(val, rels.left) &&
                        relation_operand_present(val, rels.right)) {
                      res = ActionResult<void>::fail(ParseError{
                          .code = ErrorCode::mutually_exclusive,
                          .kind = ErrorKind::validation,
                          .subject = relation_operand_label(rels.left) + ", " +
                                     relation_operand_label(rels.right),
                          .detail =
                              "these arguments cannot be provided together",
                      });
                    }
                  } else if constexpr (std::same_as<R, DependsOnRelation>) {
                    if (relation_operand_present(val, rels.source) &&
                        !relation_operand_present(val, rels.target)) {
                      res = ActionResult<void>::fail(ParseError{
                          .code = ErrorCode::dependency_missing,
                          .kind = ErrorKind::validation,
                          .subject = relation_operand_label(rels.source),
                          .detail =
                              "requires " + relation_operand_label(rels.target),
                      });
                    }
                  }
                }(),
                ...);
          },
          T::relations.items);
      return res;
    }
  }
 
  auto apply_env_fallback(T& val) -> ActionResult<void> {
    ActionResult<void> res = ActionResult<void>::ok();
    for_each_field(val, [&](auto& f) -> auto {
      using F = std::remove_cvref_t<decltype(f)>;
      if constexpr (std::derived_from<F, OptionTag>) {
        if (res.has_error() || f.provided() || f.get_param().env.empty()) return;
#ifdef _WIN32
        char* raw_buf = nullptr;
        std::size_t raw_len = 0;
        _dupenv_s(&raw_buf, &raw_len, std::string(f.get_param().env).c_str());
        std::unique_ptr<char, decltype(&free)> raw_guard(raw_buf, &free);
        const char* raw = raw_buf;
#else
        const char* raw = std::getenv(std::string(f.get_param().env).c_str());
#endif
        if (!raw) return;
        if constexpr (F::nargs.min == 0 && F::nargs.max == 0) {
          res = f.invoke_action(std::nullopt, 0, 0, 0, false);
        } else {
          res = f.invoke_action(std::string_view(raw), 0, 1, 0, false);
        }
        if (!res.has_error()) f.on_parse();
      }
    });
    return res;
  }
 
  auto finalize_special_error(ParseError error) -> ParseError {
    if (error.code == ErrorCode::help_requested && error.detail.empty()) {
      error.detail = format_help(ColorMode::detect);
    }
    return error;
  }
};

template <ArgumentSpec T>
// NOLINTNEXTLINE(cppcoreguidelines-avoid-c-arrays, modernize-avoid-c-arrays)
auto parse(int argc, char* argv[]) -> ParseResult<T> {
  return Parser<T>{}.parse(argc, argv);
}

template <ArgumentSpec T>
// NOLINTNEXTLINE(cppcoreguidelines-avoid-c-arrays, modernize-avoid-c-arrays)
auto parse_or_exit(int argc, char* argv[]) -> T {
  auto result = parse<T>(argc, argv);
  if (!result) {
    if (const auto message = result.error.message(); !message.empty()) {
      detail::write_message(result.error.use_stdout() ? stdout : stderr,
                            message);
    }
    std::exit(result.error.exit_code());
  }
  return std::move(result.value);
}
 
}  // namespace cli