arguments.hpp

// Copyright © 2026, Alexandre Coderre-Chabot.
 
// This file is part of Lector (https://github.com/acodcha/lector), a C++ library for parsing
// command line arguments. Lector is licensed under the MIT License (https://mit-license.org).
 
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
// associated documentation files (the "Software"), to deal in the Software without restriction,
// including without limitation the rights to use, copy, modify, merge, publish, distribute,
// sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
// - The above copyright notice and this permission notice shall be included in all copies or
//   substantial portions of the Software.
// - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
//   BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
//   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
//   DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM
//   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
#ifndef LECTOR_ARGUMENTS_HPP
#define LECTOR_ARGUMENTS_HPP
 
#include <algorithm>
#include <array>
#include <cstddef>
#include <cstdint>
#include <filesystem>
#include <limits>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>
#include <tuple>
#include <type_traits>
#include <unordered_set>
#include <utility>
#include <vector>
 
#include "lector/parse.hpp"
#include "lector/print.hpp"
#include "lector/text.hpp"
 
/// @brief The Lector library's namespace.
namespace lector {
 
/// @brief Arity of a command line argument.
enum class Arity : std::int8_t {
  /// @brief Unknown, unspecified, or invalid command line argument arity.
  Unknown = 0,
 
  /// @brief The command line argument has singular arity; it can only appear once on the command
  /// line.
  Singular = 1,
 
  /// @brief The command line argument has repeatable arity; it can appear multiple times on the
  /// command line. If the argument is a named repeatable argument, each appearance must include
  /// both its key and its value. If the argument is a positional repeatable argument, its multiple
  /// values must appear in an uninterrupted sequence.
  Repeatable = 2,
};
 
/// @brief Specialization of the lector::Names constant for the lector::Arity enumeration.
template <>
inline constexpr std::array<lector::Name<lector::Arity>, 3> Names<lector::Arity>{
  {
   {lector::Arity::Unknown, "Unknown"},
   {lector::Arity::Singular, "Singular"},
   {lector::Arity::Repeatable, "Repeatable"},
   }
};
 
/// @brief Specialization of the lector::Spellings constant for the lector::Arity enumeration.
template <>
inline constexpr std::array<lector::Spelling<lector::Arity>, 9> Spellings<lector::Arity>{
  {
   {"Unknown", lector::Arity::Unknown},
   {"Singular", lector::Arity::Singular},
   {"Repeatable", lector::Arity::Repeatable},
   {"unknown", lector::Arity::Unknown},
   {"singular", lector::Arity::Singular},
   {"repeatable", lector::Arity::Repeatable},
   {"UNKNOWN", lector::Arity::Unknown},
   {"SINGULAR", lector::Arity::Singular},
   {"REPEATABLE", lector::Arity::Repeatable},
   }
};
 
/// @brief Form of a command line argument.
enum class Form : std::int8_t {
  /// @brief Unknown, unspecified, or invalid command line argument form.
  Unknown = 0,
 
  /// @brief The command line argument is a positional argument; it does not define any keys and
  /// must be specified in a specific order on the command line.
  Positional = 1,
 
  /// @brief The command line argument is a named argument; it defines one or more keys and is
  /// specified on the command line by one of its keys. Named arguments can be specified in any
  /// order on the command line.
  Named = 2,
};
 
/// @brief Specialization of the lector::Names constant for the lector::Form enumeration.
template <>
inline constexpr std::array<lector::Name<lector::Form>, 3> Names<lector::Form>{
  {
   {lector::Form::Unknown, "Unknown"},
   {lector::Form::Positional, "Positional"},
   {lector::Form::Named, "Named"},
   }
};
 
/// @brief Specialization of the lector::Spellings constant for the lector::Form enumeration.
template <>
inline constexpr std::array<lector::Spelling<lector::Form>, 9> Spellings<lector::Form>{
  {
   {"Unknown", lector::Form::Unknown},
   {"Positional", lector::Form::Positional},
   {"Named", lector::Form::Named},
   {"unknown", lector::Form::Unknown},
   {"positional", lector::Form::Positional},
   {"named", lector::Form::Named},
   {"UNKNOWN", lector::Form::Unknown},
   {"POSITIONAL", lector::Form::Positional},
   {"NAMED", lector::Form::Named},
   }
};
 
/// @brief Importance of a command line argument.
enum class Importance : std::int8_t {
  /// @brief Unknown, unspecified, or invalid command line argument importance.
  Unknown = 0,
 
  /// @brief The command line argument is optional; it may or may not be provided by the user.
  Optional = 1,
 
  /// @brief The command line argument is required; it must be provided by the user.
  Required = 2,
};
 
/// @brief Specialization of the lector::Names constant for the lector::Importance enumeration.
template <>
inline constexpr std::array<lector::Name<lector::Importance>, 3> Names<lector::Importance>{
  {
   {lector::Importance::Unknown, "Unknown"},
   {lector::Importance::Optional, "Optional"},
   {lector::Importance::Required, "Required"},
   }
};
 
/// @brief Specialization of the lector::Spellings constant for the lector::Importance enumeration.
template <>
inline constexpr std::array<lector::Spelling<lector::Importance>, 9> Spellings<lector::Importance>{
  {
   {"Unknown", lector::Importance::Unknown},
   {"Optional", lector::Importance::Optional},
   {"Required", lector::Importance::Required},
   {"unknown", lector::Importance::Unknown},
   {"optional", lector::Importance::Optional},
   {"required", lector::Importance::Required},
   {"UNKNOWN", lector::Importance::Unknown},
   {"OPTIONAL", lector::Importance::Optional},
   {"REQUIRED", lector::Importance::Required},
   }
};
 
/// @brief A singular command line argument.
/// @tparam LabelValue Value of this command line argument's label. The label is used to uniquely
/// identify this command line argument in a collection of command line arguments.
/// @tparam Type The type of the value stored in this command line argument.
template <auto LabelValue, typename Type>
class SingularArgument final {
public:
  using ValueType = Type;
 
  /// @brief Default constructor. Initializes the singular command line argument with no keys, an
  /// empty description, required importance, and no default value.
  SingularArgument() noexcept = default;
 
  /// @brief Constructor for a singular positional required command line argument. No default value
  /// is needed.
  /// @param[in] description The description of the command line argument.
  /// @throws std::invalid_argument if this argument's type is boolean or if its description is
  /// empty.
  explicit SingularArgument(const std::string_view description) : description_{description} {
    validate_non_boolean_positional();
    validate_description();
  }
 
  /// @brief Constructor for a singular named required command line argument or a singular named
  /// boolean command line argument. No default value is needed. Singular named boolean command line
  /// arguments are always optional and always default to false.
  /// @param[in] keys The keys used to specify the command line argument.
  /// @param[in] description The description of the command line argument.
  /// @throws std::invalid_argument if the keys are invalid or if the description is empty.
  SingularArgument(const std::vector<std::string>& keys, const std::string_view description)
    : keys_{keys}, description_{description},
      importance_{
        std::is_same_v<Type, bool> ? lector::Importance::Optional : lector::Importance::Required} {
    set_default_value_to_false_if_boolean();
    validate_keys();
    validate_description();
  }
 
  /// @brief Constructor for a singular positional optional non-boolean command line argument. A
  /// default value must be provided.
  /// @param[in] description The description of the command line argument.
  /// @param[in] default_value The default value of the command line argument.
  /// @throws std::invalid_argument if this argument's type is boolean or if its description is
  /// empty.
  SingularArgument(const std::string_view description, const Type& default_value)
    : description_{description}, default_value_{default_value},
      importance_{lector::Importance::Optional} {
    validate_non_boolean_default_value();
    validate_description();
  }
 
  /// @brief Constructor for a singular named optional non-boolean command line argument. A default
  /// value must be provided.
  /// @param[in] keys The keys used to specify the command line argument.
  /// @param[in] description The description of the command line argument.
  /// @param[in] default_value The default value of the command line argument.
  /// @throws std::invalid_argument if this argument's type is boolean, if its keys are invalid, or
  /// if its description is empty.
  SingularArgument(const std::vector<std::string>& keys, const std::string_view description,
                   const Type& default_value)
    : keys_{keys}, description_{description}, default_value_{default_value},
      importance_{lector::Importance::Optional} {
    validate_non_boolean_default_value();
    validate_keys();
    validate_description();
  }
 
  /// @brief Destructor. Destroys this singular command line argument.
  ~SingularArgument() noexcept = default;
 
  /// @brief Copy constructor. Constructs a singular command line argument by copying another one.
  SingularArgument(const lector::SingularArgument<LabelValue, Type>&) = default;
 
  /// @brief Copy assignment operator. Assigns this singular command line argument by copying
  /// another one.
  /// @return This singular command line argument after the assignment.
  lector::SingularArgument<LabelValue, Type>& operator=(
      const lector::SingularArgument<LabelValue, Type>&) = default;
 
  /// @brief Move constructor. Constructs a singular command line argument by moving another one.
  SingularArgument(lector::SingularArgument<LabelValue, Type>&&) noexcept = default;
 
  /// @brief Move assignment operator. Assigns this singular command line argument by moving another
  /// one.
  /// @return This singular command line argument after the assignment.
  lector::SingularArgument<LabelValue, Type>& operator=(
      lector::SingularArgument<LabelValue, Type>&&) noexcept = default;
 
  /// @brief Label of this command line argument. Used to uniquely identify this command line
  /// argument in a collection of command line arguments. Set at construction.
  /// @return The label of this command line argument.
  [[nodiscard]] static constexpr auto label() noexcept {
    return LabelValue;
  }
 
  /// @brief Keys that can be used to specify this argument on the command line if it is a named
  /// argument, or an empty collection if this argument is a positional argument. Set at
  /// construction.
  /// @return The keys that can be used to specify this command line argument.
  [[nodiscard]] const std::vector<std::string>& keys() const noexcept {
    return keys_;
  }
 
  /// @brief Description of this command line argument. Set at construction.
  /// @return The description of this command line argument.
  [[nodiscard]] std::string_view description() const noexcept {
    return description_;
  }
 
  /// @brief Returns whether this singular command line argument has a default value.
  /// @return True if this singular command line argument has a default value; false if it does not.
  [[nodiscard]] bool has_default() const noexcept {
    return default_value_.has_value();
  }
 
  /// @brief Default value of this singular command line argument if it is optional and non-boolean,
  /// or std::nullopt otherwise. Set at construction.
  /// @return The default value of this singular command line argument.
  [[nodiscard]] const std::optional<Type>& default_value() const noexcept {
    return default_value_;
  }
 
  /// @brief Returns whether this singular command line argument has a parsed value.
  /// @return True if this singular command line argument has a parsed value; false if it does not.
  [[nodiscard]] bool has_parsed() const noexcept {
    return parsed_value_.has_value();
  }
 
  /// @brief Parsed value of this singular command line argument. Set when this argument is parsed
  /// from the command line.
  /// @return The parsed value of this singular command line argument.
  [[nodiscard]] const std::optional<Type>& parsed_value() const noexcept {
    return parsed_value_;
  }
 
  /// @brief Importance of this command line argument. A required argument must be provided by the
  /// user on the command line, whereas an optional argument may or may not be provided by the user
  /// on the command line. Set at construction.
  /// @return The importance of this command line argument.
  [[nodiscard]] lector::Importance importance() const noexcept {
    return importance_;
  }
 
  /// @brief Form of this command line argument. A positional argument does not define any keys and
  /// must be specified in a specific order on the command line, whereas a named argument defines
  /// one or more keys and is specified on the command line by one of its keys. Named arguments can
  /// be specified in any order on the command line.
  /// @return The form of this command line argument.
  [[nodiscard]] lector::Form form() const noexcept {
    if (keys_.empty()) {
      return lector::Form::Positional;
    }
    return lector::Form::Named;
  }
 
  /// @brief Arity of this command line argument. A singular argument can only appear once on the
  /// command line, whereas a repeatable argument can appear multiple times.
  /// @return The arity of this command line argument.
  [[nodiscard]] static lector::Arity arity() noexcept {
    return lector::Arity::Singular;
  }
 
  /// @brief Value of this singular command line argument. Returns the parsed value if it exists;
  /// otherwise, returns the default value.
  /// @return The value of this singular command line argument.
  /// @throws std::logic_error if this singular command line argument is missing both its parsed
  /// value and its default value. Cannot occur in practice due to checks done at construction.
  [[nodiscard]] const Type& parsed_or_default_value() const {
    if (parsed_value_.has_value()) {
      return parsed_value_.value();
    }
    if (default_value_.has_value()) {
      return default_value_.value();
    }
    throw std::logic_error("No parsed or default value for argument '" + options() + "'.");
  }
 
  /// @brief Sets the parsed value of this singular command line argument.
  /// @param[in] value The parsed value to set.
  /// @throws std::logic_error if this singular command line argument is default-constructed or if a
  /// parsed value has already been set for this singular command line argument.
  /// @throws std::invalid_argument if this singular command line argument is boolean and the parsed
  /// value is false.
  void set_parsed_value(const Type& value) {
    if (description_.empty()) {
      throw std::logic_error("Default-constructed arguments cannot parse values.");
    }
    if constexpr (std::is_same_v<Type, bool>) {
      if (!value) {
        throw std::invalid_argument("Boolean arguments can only be parsed as true.");
      }
    }
    if (parsed_value_.has_value()) {
      throw std::logic_error("A singular argument cannot have more than one parsed value.");
    }
    parsed_value_ = value;
  }
 
  /// @brief Prints the longest key of this command line argument with its associated value type as
  /// a string of text.
  /// @return The string of text that contains the longest key of this command line argument with
  /// its associated value type.
  [[nodiscard]] std::string longest_key_with_value_type() const {
    if (keys_.empty()) {
      return std::string{value_type()};
    }
    std::string result{longest_key()};
    const std::string type{value_type()};
    if (!type.empty()) {
      result.push_back(' ');
      result.append(type);
    }
    return result;
  }
 
  /// @brief Prints the keys and value type of this command line argument as a string of text.
  /// @return The string of text that contains the keys and value type of this command line
  /// argument.
  [[nodiscard]] std::string keys_with_value_type() const {
    if (keys_.empty()) {
      return std::string{value_type()};
    }
    std::string result;
    for (std::size_t index{0UL}; index < keys_.size(); ++index) {
      const std::string type{value_type()};
      result.append(keys_.at(index));
      if (!type.empty()) {
        result.push_back(' ');
        result.append(type);
      }
      if (index + 1 < keys_.size()) {
        result.append(", ");
      }
    }
    return result;
  }
 
  /// @brief Prints the usage information of this command line argument as a string of text. The
  /// usage information consists of this command line argument's longest key and value type,
  /// enclosed in square braces if this command line argument is optional.
  /// @return The string of text that contains the usage information of this command line argument.
  [[nodiscard]] std::string usage() const {
    if (importance() == lector::Importance::Optional) {
      return "[" + longest_key_with_value_type() + "]";
    }
    return longest_key_with_value_type();
  }
 
  /// @brief Prints the options information of this command line argument as a string of text. The
  /// options information consists of this command line argument's keys, value type, and
  /// description.
  /// @return The string of text that contains the options information of this command line
  /// argument.
  [[nodiscard]] std::string options() const {
    std::string keys_with_value_type_{keys_with_value_type()};
    if (keys_with_value_type_.empty()) {
      return description_;
    }
    if (description_.empty()) {
      return keys_with_value_type_;
    }
    return keys_with_value_type_ + "  " + description_;
  }
 
  /// @brief Prints the execution of this command line argument as a string of text. The execution
  /// consists of this command line argument's longest key and parsed value, if any.
  /// @return The string of text that contains the execution of this command line argument.
  [[nodiscard]] std::string execution() const {
    if constexpr (std::is_same_v<Type, bool>) {
      return execution_boolean();
    } else {
      return execution_non_boolean();
    }
  }
 
private:
  /// @brief If this command line argument is boolean, sets its default value to false. Boolean
  /// command line arguments are always optional and always default to false.
  void set_default_value_to_false_if_boolean() {
    if constexpr (std::is_same_v<Type, bool>) {
      default_value_ = false;
    }
  }
 
  /// @brief Validates that this positional command line argument is not boolean. Boolean command
  /// line arguments must always specify one or more keys and therefore cannot be positional.
  void validate_non_boolean_positional() const {
    if constexpr (std::is_same_v<Type, bool>) {
      throw std::invalid_argument("Boolean arguments must specify one or more keys.");
    }
  }
 
  /// @brief Validates that this command line argument that specifies a default value is not
  /// boolean. Boolean command line arguments are always optional and always default to false, so
  /// they cannot specify default values.
  void validate_non_boolean_default_value() const {
    if constexpr (std::is_same_v<Type, bool>) {
      throw std::invalid_argument(
          "Boolean arguments cannot specify default values; they are always false by default.");
    }
  }
 
  /// @brief Validates the keys of this command line argument.
  /// @throws std::logic_error if the keys are missing or invalid.
  void validate_keys() const {
    if (keys_.empty()) {
      throw std::logic_error("All named arguments must each have at least one key.");
    }
    for (const std::string& key : keys_) {
      if (key.empty()) {
        throw std::logic_error("Empty key in named argument '" + options()
                               + "'. Named arguments cannot have empty keys.");
      }
    }
    const std::size_t keys_size{keys_.size()};
    for (std::size_t first{0UL}; first < keys_size; ++first) {
      for (std::size_t second{first + static_cast<std::size_t>(1UL)}; second < keys_size;
           ++second) {
        if (keys_.at(first) == keys_.at(second)) {
          throw std::logic_error("Duplicate key '" + keys_.at(first) + "' in named argument '"
                                 + options() + "'. Named arguments cannot have duplicate keys.");
        }
      }
    }
  }
 
  /// @brief Validates the description of this command line argument.
  /// @throws std::logic_error if the description of this command line argument is empty.
  void validate_description() const {
    if (description_.empty()) {
      throw std::logic_error("Empty description in argument '" + options()
                             + "'. All arguments must have descriptions.");
    }
  }
 
  /// @brief Prints the value type of this command line argument as a string of text.
  /// @return The string of text that contains the value type of this command line argument.
  [[nodiscard]] constexpr std::string_view value_type() const {
    if constexpr (std::is_same_v<Type, bool>) {
      return "";
    } else if constexpr (std::numeric_limits<Type>::is_integer) {
      return "<number>";
    } else if constexpr (std::is_floating_point_v<Type>) {
      return "<value>";
    } else if constexpr (
        std::is_same_v<Type, std::string> || std::is_same_v<Type, std::string_view>) {
      return "<text>";
    } else if constexpr (std::is_same_v<Type, std::filesystem::path>) {
      return "<path>";
    } else {
      return "<value>";
    }
  }
 
  /// @brief Returns the longest key of this command line argument.
  /// @return The longest key of this command line argument.
  /// @throws std::out_of_range if this command line argument has no keys.
  [[nodiscard]] const std::string& longest_key() const {
    std::size_t longest_key_index{0UL};
    std::size_t longest_key_length{0UL};
    for (std::size_t index{0UL}; index < keys_.size(); ++index) {
      const std::size_t length{lector::count_code_points(keys_.at(index))};
      if (length > longest_key_length) {
        longest_key_index = index;
        longest_key_length = length;
      }
    }
    return keys_.at(longest_key_index);
  }
 
  /// @brief Prints the execution of this boolean command line argument as a string of text. The
  /// execution consists of this boolean command line argument's longest key.
  /// @return The string of text that contains the execution of this boolean command line argument.
  [[nodiscard]] std::string execution_boolean() const {
    if (parsed_value_.has_value() && parsed_value_.value()) {
      return longest_key();
    }
    return std::string{};
  }
 
  /// @brief Prints the execution of this non-boolean command line argument as a string of text. The
  /// execution consists of this non-boolean command line argument's longest key and parsed value,
  /// if any.
  /// @return The string of text that contains the execution of this non-boolean command line
  /// argument.
  [[nodiscard]] std::string execution_non_boolean() const {
    if (parsed_value_.has_value()) {
      if (keys_.empty()) {
        return lector::quote_if_contains_whitespace(lector::print<Type>(parsed_value_.value()));
      }
      return longest_key() + " "
             + lector::quote_if_contains_whitespace(lector::print<Type>(parsed_value_.value()));
    }
    return std::string{};
  }
 
  /// @brief Keys that can be used to specify this argument on the command line if it is a named
  /// argument, or an empty collection if this argument is a positional argument. Set at
  /// construction.
  std::vector<std::string> keys_;
 
  /// @brief Description of this command line argument. Set at construction.
  std::string description_;
 
  /// @brief Default value of this singular command line argument if it is optional and non-boolean,
  /// or std::nullopt otherwise. Set at construction.
  std::optional<Type> default_value_;
 
  /// @brief Parsed value of this singular command line argument. Set when this argument is parsed
  /// from the command line.
  std::optional<Type> parsed_value_;
 
  /// @brief Importance of this command line argument. A required argument must be provided by the
  /// user on the command line, whereas an optional argument may or may not be provided by the user
  /// on the command line. Set at construction.
  lector::Importance importance_{lector::Importance::Required};
};
 
/// @brief A repeatable command line argument.
/// @tparam LabelValue Value of this command line argument's label. The label is used to uniquely
/// identify this command line argument in a collection of command line arguments.
/// @tparam Type The type of the value stored in this command line argument.
template <auto LabelValue, typename Type>
class RepeatableArgument final {
public:
  using ValueType = Type;
 
  /// @brief Default constructor. Initializes the repeatable command line argument with no keys, an
  /// empty description, required importance, and no default values.
  RepeatableArgument() noexcept = default;
 
  /// @brief Constructor for a repeatable positional required command line argument. No default
  /// values are needed.
  /// @param[in] description The description of the command line argument.
  /// @throws std::invalid_argument if the type is boolean or if the description is empty.
  explicit RepeatableArgument(const std::string_view description) : description_{description} {
    validate_non_boolean_positional();
    validate_description();
  }
 
  /// @brief Constructor for a repeatable named required command line argument or a repeatable named
  /// optional boolean command line argument. No default value is needed. Repeatable named boolean
  /// command line arguments are always optional and always default to false.
  /// @param[in] keys The keys used to specify the command line argument.
  /// @param[in] description The description of the command line argument.
  /// @throws std::invalid_argument if the keys are invalid or if the description is empty.
  RepeatableArgument(const std::vector<std::string>& keys, const std::string_view description)
    : keys_{keys}, description_{description},
      importance_{
        std::is_same_v<Type, bool> ? lector::Importance::Optional : lector::Importance::Required} {
    validate_keys();
    validate_description();
  }
 
  /// @brief Constructor for a repeatable positional optional non-boolean command line argument.
  /// @param[in] description The description of the command line argument.
  /// @param[in] default_values The default values of the command line argument, if any.
  /// @throws std::invalid_argument if the type is boolean or if the description is empty.
  RepeatableArgument(const std::string_view description, const std::vector<Type>& default_values)
    : description_{description}, default_values_{default_values},
      importance_{lector::Importance::Optional} {
    validate_non_boolean_default_values();
    validate_description();
  }
 
  /// @brief Constructor for a repeatable named optional non-boolean command line argument.
  /// @param[in] keys The keys used to specify the command line argument.
  /// @param[in] description The description of the command line argument.
  /// @param[in] default_values The default values of the command line argument, if any.
  /// @throws std::invalid_argument if the type is boolean, if the keys are invalid, or if the
  /// description is empty.
  RepeatableArgument(const std::vector<std::string>& keys, const std::string_view description,
                     const std::vector<Type>& default_values)
    : keys_{keys}, description_{description}, default_values_{default_values},
      importance_{lector::Importance::Optional} {
    validate_non_boolean_default_values();
    validate_keys();
    validate_description();
  }
 
  /// @brief Destructor. Destroys this repeatable command line argument.
  ~RepeatableArgument() noexcept = default;
 
  /// @brief Copy constructor. Constructs a repeatable command line argument by copying another one.
  RepeatableArgument(const lector::RepeatableArgument<LabelValue, Type>&) = default;
 
  /// @brief Copy assignment operator. Assigns this repeatable command line argument by copying
  /// another one.
  /// @return This repeatable command line argument after the assignment.
  lector::RepeatableArgument<LabelValue, Type>& operator=(
      const lector::RepeatableArgument<LabelValue, Type>&) = default;
 
  /// @brief Move constructor. Constructs a repeatable command line argument by moving another one.
  RepeatableArgument(lector::RepeatableArgument<LabelValue, Type>&&) noexcept = default;
 
  /// @brief Move assignment operator. Assigns this repeatable command line argument by moving
  /// another one.
  /// @return This repeatable command line argument after the assignment.
  lector::RepeatableArgument<LabelValue, Type>& operator=(
      lector::RepeatableArgument<LabelValue, Type>&&) noexcept = default;
 
  /// @brief Label of this command line argument. Used to uniquely identify this command line
  /// argument in a collection of command line arguments. Set at construction.
  /// @return The label of this command line argument.
  [[nodiscard]] static constexpr auto label() noexcept {
    return LabelValue;
  }
 
  /// @brief Keys that can be used to specify this argument on the command line if it is a named
  /// argument, or an empty collection if this argument is a positional argument. Set at
  /// construction.
  /// @return The keys that can be used to specify this command line argument.
  [[nodiscard]] const std::vector<std::string>& keys() const noexcept {
    return keys_;
  }
 
  /// @brief Description of this command line argument. Set at construction.
  /// @return The description of this command line argument.
  [[nodiscard]] std::string_view description() const noexcept {
    return description_;
  }
 
  /// @brief Returns whether this repeatable command line argument has one or more default values.
  /// @return True if this repeatable command line argument has one or more default values; false if
  /// it has none.
  [[nodiscard]] bool has_default() const noexcept {
    return !default_values_.empty();
  }
 
  /// @brief Default values of this repeatable command line argument. Set at construction.
  /// @return The default values of this repeatable command line argument.
  [[nodiscard]] const std::vector<Type>& default_values() const noexcept {
    return default_values_;
  }
 
  /// @brief Returns whether this repeatable command line argument has one or more parsed values.
  /// @return True if this repeatable command line argument has one or more parsed values; false if
  /// it has none.
  [[nodiscard]] bool has_parsed() const noexcept {
    return !parsed_values_.empty();
  }
 
  /// @brief Parsed values of this repeatable command line argument. Set when this argument is
  /// parsed from the command line.
  /// @return The parsed values of this repeatable command line argument.
  [[nodiscard]] const std::vector<Type>& parsed_values() const noexcept {
    return parsed_values_;
  }
 
  /// @brief Importance of this command line argument. A required argument must be provided by the
  /// user on the command line, whereas an optional argument may or may not be provided by the user
  /// on the command line. Set at construction.
  /// @return The importance of this command line argument.
  [[nodiscard]] lector::Importance importance() const noexcept {
    return importance_;
  }
 
  /// @brief Form of this command line argument. A positional argument does not define any keys and
  /// must be specified in a specific order on the command line, whereas a named argument defines
  /// one or more keys and is specified on the command line by one of its keys. Named arguments can
  /// be specified in any order on the command line.
  /// @return The form of this command line argument.
  [[nodiscard]] lector::Form form() const noexcept {
    if (keys_.empty()) {
      return lector::Form::Positional;
    }
    return lector::Form::Named;
  }
 
  /// @brief Arity of this command line argument. A repeatable argument can only appear once on the
  /// command line, whereas a repeatable argument can appear multiple times.
  /// @return The arity of this command line argument.
  [[nodiscard]] static lector::Arity arity() noexcept {
    return lector::Arity::Repeatable;
  }
 
  /// @brief Values of this repeatable command line argument. Returns the parsed values if they
  /// exist; otherwise, returns the default values.
  /// @return The values of this repeatable command line argument.
  [[nodiscard]] const std::vector<Type>& parsed_or_default_values() const {
    if (!parsed_values_.empty()) {
      return parsed_values_;
    }
    return default_values_;
  }
 
  /// @brief Inserts an additional parsed value into this repeatable command line argument.
  /// @param[in] value The parsed value to insert.
  /// @throws std::logic_error if this repeatable command line argument is default-constructed.
  /// @throws std::invalid_argument if this repeatable command line argument is boolean and the
  /// parsed value is false.
  void set_parsed_value(const Type& value) {
    if (description_.empty()) {
      throw std::logic_error("Default-constructed arguments cannot parse values.");
    }
    if constexpr (std::is_same_v<Type, bool>) {
      if (!value) {
        throw std::invalid_argument("Boolean arguments can only be parsed as true.");
      }
    }
    parsed_values_.push_back(value);
  }
 
  /// @brief Prints the longest key of this command line argument with its associated value type as
  /// a string of text.
  /// @return The string of text that contains the longest key of this command line argument with
  /// its associated value type.
  [[nodiscard]] std::string longest_key_with_value_type() const {
    if (keys_.empty()) {
      return std::string{value_type()};
    }
    std::string result{longest_key()};
    const std::string type{value_type()};
    if (!type.empty()) {
      result.push_back(' ');
      result.append(type);
    }
    return result;
  }
 
  /// @brief Prints the keys and value type of this command line argument as a string of text.
  /// @return The string of text that contains the keys and value type of this command line
  /// argument.
  [[nodiscard]] std::string keys_with_value_type() const {
    if (keys_.empty()) {
      return std::string{value_type()};
    }
    std::string result;
    for (std::size_t index{0UL}; index < keys_.size(); ++index) {
      const std::string type{value_type()};
      result.append(keys_.at(index));
      if (!type.empty()) {
        result.push_back(' ');
        result.append(type);
      }
      if (index + 1 < keys_.size()) {
        result.append(", ");
      }
    }
    return result;
  }
 
  /// @brief Prints the usage information of this command line argument as a string of text. The
  /// usage information consists of this command line argument's longest key and value type,
  /// enclosed in square braces if this command line argument is optional.
  /// @return The string of text that contains the usage information of this command line argument.
  [[nodiscard]] std::string usage() const {
    const std::string longest_key_with_value_type_{longest_key_with_value_type()};
    if (importance() == lector::Importance::Optional) {
      return "[" + longest_key_with_value_type_ + "] ...";
    }
    if (longest_key_with_value_type_.empty()) {
      return "...";
    }
    return longest_key_with_value_type_ + " ...";
  }
 
  /// @brief Prints the options information of this command line argument as a string of text. The
  /// options information consists of this command line argument's keys, value type, and
  /// description.
  /// @return The string of text that contains the options information of this command line
  /// argument.
  [[nodiscard]] std::string options() const {
    std::string keys_with_value_type_{keys_with_value_type()};
    if (keys_with_value_type_.empty()) {
      return description_;
    }
    if (description_.empty()) {
      return keys_with_value_type_;
    }
    return keys_with_value_type_ + "  " + description_;
  }
 
  /// @brief Prints the execution of this command line argument as a string of text. The execution
  /// consists of this command line argument's longest key and parsed values, if any.
  /// @return The string of text that contains the execution of this command line argument.
  [[nodiscard]] std::string execution() const {
    if constexpr (std::is_same_v<Type, bool>) {
      return execution_boolean();
    } else {
      return execution_non_boolean();
    }
  }
 
private:
  /// @brief Validates that this positional command line argument is not boolean. Boolean command
  /// line arguments must always specify one or more keys and therefore cannot be positional.
  void constexpr validate_non_boolean_positional() const {
    if constexpr (std::is_same_v<Type, bool>) {
      throw std::invalid_argument("Boolean arguments must specify one or more keys.");
    }
  }
 
  /// @brief Validates that this command line argument that specifies one or more default values is
  /// not boolean. Boolean command line arguments are always optional and always default to false,
  /// so they cannot specify default values.
  void constexpr validate_non_boolean_default_values() const {
    if constexpr (std::is_same_v<Type, bool>) {
      throw std::invalid_argument(
          "Boolean arguments cannot specify default values; they are always false by default.");
    }
  }
 
  /// @brief Validates the keys of this command line argument.
  /// @throws std::logic_error if the keys are missing or invalid.
  void validate_keys() const {
    if (keys_.empty()) {
      throw std::logic_error("All named arguments must each have at least one key.");
    }
    for (const std::string& key : keys_) {
      if (key.empty()) {
        throw std::logic_error("Empty key in named argument '" + options()
                               + "'. Named arguments cannot have empty keys.");
      }
    }
    const std::size_t keys_size{keys_.size()};
    for (std::size_t first{0UL}; first < keys_size; ++first) {
      for (std::size_t second{first + static_cast<std::size_t>(1UL)}; second < keys_size;
           ++second) {
        if (keys_.at(first) == keys_.at(second)) {
          throw std::logic_error("Duplicate key '" + keys_.at(first) + "' in named argument '"
                                 + options() + "'. Named arguments cannot have duplicate keys.");
        }
      }
    }
  }
 
  /// @brief Validates the description of this command line argument.
  /// @throws std::logic_error if the description of this command line argument is empty.
  void validate_description() const {
    if (description_.empty()) {
      throw std::logic_error("Empty description in argument '" + options()
                             + "'. All arguments must have descriptions.");
    }
  }
 
  /// @brief Prints the value type of this command line argument as a string of text.
  /// @return The string of text that contains the value type of this command line argument.
  [[nodiscard]] constexpr std::string_view value_type() const {
    if constexpr (std::is_same_v<Type, bool>) {
      return "";
    } else if constexpr (std::numeric_limits<Type>::is_integer) {
      return "<number>";
    } else if constexpr (std::is_floating_point_v<Type>) {
      return "<value>";
    } else if constexpr (
        std::is_same_v<Type, std::string> || std::is_same_v<Type, std::string_view>) {
      return "<text>";
    } else if constexpr (std::is_same_v<Type, std::filesystem::path>) {
      return "<path>";
    } else {
      return "<value>";
    }
  }
 
  /// @brief Returns the longest key of this command line argument.
  /// @return The longest key of this command line argument.
  /// @throws std::out_of_range if this command line argument has no keys.
  [[nodiscard]] const std::string& longest_key() const {
    std::size_t longest_key_index{0UL};
    std::size_t longest_key_length{0UL};
    for (std::size_t index{0UL}; index < keys_.size(); ++index) {
      const std::size_t length{lector::count_code_points(keys_.at(index))};
      if (length > longest_key_length) {
        longest_key_index = index;
        longest_key_length = length;
      }
    }
    return keys_.at(longest_key_index);
  }
 
  /// @brief Prints the execution of this boolean command line argument as a string of text. The
  /// execution consists of this boolean command line argument's longest key for each parsed value.
  /// @return The string of text that contains the execution of this boolean command line argument.
  [[nodiscard]] std::string execution_boolean() const {
    std::string result;
    for (const Type& parsed_value : parsed_values_) {
      if (parsed_value) {
        if (!result.empty()) {
          result.push_back(' ');
        }
        result.append(longest_key());
      }
    }
    return result;
  }
 
  /// @brief Prints the execution of this non-boolean command line argument as a string of text. The
  /// execution consists of this non-boolean command line argument's longest key and parsed values,
  /// if any.
  /// @return The string of text that contains the execution of this non-boolean command line
  /// argument.
  [[nodiscard]] std::string execution_non_boolean() const {
    if (keys_.empty()) {
      std::string result;
      for (const Type& parsed_value : parsed_values_) {
        if (!result.empty()) {
          result.push_back(' ');
        }
        result.append(lector::quote_if_contains_whitespace(lector::print<Type>(parsed_value)));
      }
      return result;
    }
    std::string result;
    for (const Type& parsed_value : parsed_values_) {
      if (!result.empty()) {
        result.push_back(' ');
      }
      result.append(longest_key());
      result.push_back(' ');
      result.append(lector::quote_if_contains_whitespace(lector::print<Type>(parsed_value)));
    }
    return result;
  }
 
  /// @brief Keys that can be used to specify this argument on the command line if it is a named
  /// argument, or an empty collection if this argument is a positional argument. Set at
  /// construction.
  std::vector<std::string> keys_;
 
  /// @brief Description of this command line argument. Set at construction.
  std::string description_;
 
  /// @brief Default values of this repeatable command line argument. Set at construction.
  std::vector<Type> default_values_;
 
  /// @brief Parsed values of this repeatable command line argument. Set when this argument is
  /// parsed from the command line.
  std::vector<Type> parsed_values_;
 
  /// @brief Importance of this command line argument. A required argument must be provided by the
  /// user on the command line, whereas an optional argument may or may not be provided by the user
  /// on the command line. Set at construction.
  lector::Importance importance_{lector::Importance::Required};
};
 
/// @brief Configuration of the help information of a collection of command line arguments.
struct Configuration final {
public:
  /// @brief Title of the application whose command line arguments are to be parsed. When the
  /// collection of command line arguments' help information is printed, this title appears first,
  /// before its usage information. Optional and empty by default, in which case no title is
  /// printed.
  std::optional<std::string> title{std::nullopt};
 
  /// @brief Description of the application whose command line arguments are to be parsed. When the
  /// collection of command line arguments' help information is printed, this description appears
  /// between its usage information and its options information. Optional and empty by default, in
  /// which case no description is printed.
  std::optional<std::string> description{std::nullopt};
 
  /// @brief Additional notes pertaining to the application whose command line arguments are to be
  /// parsed. When the collection of command line arguments' help information is printed, these
  /// notes appear last, after its options information. Optional and empty by default, in which case
  /// no notes are printed.
  std::optional<std::string> notes{std::nullopt};
};
 
/// @brief Type trait used to extract a command line argument from a collection of command line
/// arguments, using only its Label.
/// @tparam Label The label of the command line argument to extract.
/// @tparam ...ArgumentTypes The variadic list of argument types in the collection of command line
/// arguments.
template <auto Label, typename... ArgumentTypes>
struct FindArgumentByLabel;
 
/// @brief Type trait to provide short-circuit evaluation for lector::FindArgumentByLabel.
/// @tparam Label The label of the command line argument to extract.
/// @tparam Match Whether the command line argument was found or not.
/// @tparam FirstArgument The type of the command line argument to extract.
/// @tparam ...RemainingArgumentTypes The variadic list of argument types in the collection of
/// command line arguments, excluding the command line argument to extract.
template <auto Label, bool Match, typename FirstArgument, typename... RemainingArgumentTypes>
struct FindArgument;
 
/// @brief True branch of the short-circuit evaluation type trait. The command line argument has
/// been found and will now be returned; the remaining command line arguments do not need to be
/// searched.
/// @tparam Label The label of the command line argument to extract.
/// @tparam FirstArgument The type of the command line argument to extract.
/// @tparam ...RemainingArgumentTypes The variadic list of argument types in the collection of
/// command line arguments, excluding the command line argument to extract.
template <auto Label, typename FirstArgument, typename... RemainingArgumentTypes>
struct FindArgument<Label, true, FirstArgument, RemainingArgumentTypes...> {
  using type = FirstArgument;
};
 
/// @brief False branch of the short-circuit evaluation type trait. The command line argument has
/// not yet been found and the remaining command line arguments should be searched.
/// @tparam Label The label of the command line argument to extract.
/// @tparam FirstArgument The type of the command line argument to extract.
/// @tparam ...RemainingArgumentTypes The variadic list of argument types in the collection of
/// command line arguments, excluding the command line argument to extract.
template <auto Label, typename FirstArgument, typename... RemainingArgumentTypes>
struct FindArgument<Label, false, FirstArgument, RemainingArgumentTypes...> {
  using type = typename FindArgumentByLabel<Label, RemainingArgumentTypes...>::type;
};
 
/// @brief Type trait specialization used to extract a command line argument from a collection of
/// command line arguments, using its Label and the types of the remaining command line arguments in
/// the collection.
/// @tparam Label The label of the command line argument to extract.
/// @tparam FirstArgument The type of the command line argument to extract.
/// @tparam ...RemainingArgumentTypes The variadic list of argument types in the collection of
/// command line arguments, excluding the command line argument to extract.
template <auto Label, typename FirstArgument, typename... RemainingArgumentTypes>
struct FindArgumentByLabel<Label, FirstArgument, RemainingArgumentTypes...> {
  using type = typename FindArgument<Label, (FirstArgument::label() == Label), FirstArgument,
                                     RemainingArgumentTypes...>::type;
};
 
/// @brief Type trait that validates at compilation time that a specified variadic list of types are
/// unique. Base type trait that contains an empty list of types and returns true.
/// @tparam ...Types Variadic list of types to check for uniqueness.
template <auto... Types>
struct AreUnique : std::true_type {};
 
/// @brief Type trait that validates at compilation time that a specified variadic list of types are
/// unique. Recursively compares a first type against the remaining variadic list of types.
/// @tparam FirstType The first type to compare.
/// @tparam ...RemainingTypes The remaining types in the variadic list of types to compare.
template <auto FirstType, auto... RemainingTypes>
struct AreUnique<FirstType, RemainingTypes...>
  : std::bool_constant<((FirstType != RemainingTypes) && ...)
                       && AreUnique<RemainingTypes...>::value> {};
 
/// @brief A collection of command line arguments that can be parsed from argc and argv.
/// @tparam ...ArgumentTypes Variadic list of the types of the command line arguments in this
/// collection.
template <typename... ArgumentTypes>
class Arguments final {
public:
  /// @brief Compile-time check that all arguments have unique labels.
  static_assert(AreUnique<ArgumentTypes::label()...>::value,
                "Duplicate argument labels detected. Each argument must have a unique label.");
 
  /// @brief Constructor. Constructs a collection of command line arguments from a configuration
  /// data structure and a variadic list of command line arguments.
  /// @param[in] configuration The configuration data structure.
  /// @param[in] arguments... The variadic list of command line arguments.
  /// @throws std::logic_error if the command line arguments are invalid.
  explicit Arguments(const lector::Configuration& configuration, const ArgumentTypes&... arguments)
    : configuration_{configuration}, arguments_{arguments...} {
    validate_arguments();
  }
 
  /// @brief Constructor. Constructs a collection of command line arguments from a variadic list of
  /// command line arguments.
  /// @param[in] arguments... The variadic list of command line arguments.
  /// @throws std::logic_error if the command line arguments are invalid.
  explicit Arguments(const ArgumentTypes&... arguments) : arguments_{arguments...} {
    validate_arguments();
  }
 
  /// @brief Destructor. Destroys this collection of command line arguments.
  ~Arguments() noexcept = default;
 
  /// @brief Copy constructor. Constructs a collection of command line argument by copying another
  /// one.
  Arguments(const lector::Arguments<ArgumentTypes...>&) = default;
 
  /// @brief Copy assignment operator. Assigns this collection of command line argument by copying
  /// another one.
  /// @return This collection of command line argument after the assignment.
  lector::Arguments<ArgumentTypes...>& operator=(
      const lector::Arguments<ArgumentTypes...>&) = default;
 
  /// @brief Move constructor. Constructs a collection of command line argument by moving another
  /// one.
  Arguments(lector::Arguments<ArgumentTypes...>&&) noexcept = default;
 
  /// @brief Move assignment operator. Assigns this collection of command line argument by moving
  /// another one.
  /// @return This collection of command line argument after the assignment.
  lector::Arguments<ArgumentTypes...>& operator=(
      lector::Arguments<ArgumentTypes...>&&) noexcept = default;
 
  /// @brief Parses argc and argv to populate the parsed values of the command line arguments in
  /// this collection. This method should be called before calling the validate() method.
  /// @param[in] argc The number of command line arguments, including the executable path.
  /// @param[in] argv The array of C-strings that represents the command line arguments, starting
  /// with the executable path.
  /// @throws std::invalid_argument if an invalid, unknown, duplicate, or missing argument is
  /// encountered.
  void parse(const int argc, char* argv[]) {
    parse_executable_path(argc, argv);
    const std::vector<std::string_view> positional_tokens{parse_named_arguments(argc, argv)};
    parse_positional_arguments(positional_tokens);
  }
 
  /// @brief Validates that all required arguments have each successfully parsed a value from the
  /// command line. Should only be called after the lector::Arguments::parse() method has been
  /// called. If any command line arguments require special consideration, such as --version or
  /// --help flags, they should be handled before calling this method.
  /// @throws std::invalid_argument if any required arguments are lacking parsed values.
  void validate() const {
    std::apply(
        [&](const auto&... argument) {
          (..., [&] {
            if (argument.importance() == lector::Importance::Required && !argument.has_parsed()) {
              throw std::invalid_argument(
                  "Missing required argument '" + argument.options() + "'.");
            }
          }());
        },
        arguments_);
  }
 
  /// @brief Returns the configuration of the help information of this collection of command line
  /// arguments.
  /// @return The configuration of the help information of this collection of command line
  /// arguments.
  [[nodiscard]] const lector::Configuration& configuration() const {
    return configuration_;
  }
 
  /// @brief Returns the executable path of this collection of command line arguments. If the
  /// command line arguments have not yet been parsed from argc and argv, this path is empty.
  /// @return The executable path of this collection of command line arguments.
  [[nodiscard]] const std::filesystem::path& executable_path() const {
    return executable_path_;
  }
 
  /// @brief Returns a specified command line argument from this collection.
  /// @tparam Label The label of the command line argument to return.
  /// @return The specified command line argument.
  template <auto Label>
  [[nodiscard]] const auto& get() const {
    using Type = typename lector::FindArgumentByLabel<Label, ArgumentTypes...>::type;
    return std::get<Type>(arguments_);
  }
 
  /// @brief Prints the usage information of this collection of command line arguments as a string
  /// of text. The usage information consists of each argument's longest key and value type,
  /// enclosed in square braces for optional command line arguments.
  /// @return The string of text that contains the usage information of this collection of command
  /// line arguments.
  [[nodiscard]] std::string usage() const {
    return usage(std::numeric_limits<std::size_t>::max());
  }
 
  /// @brief Prints the usage information of this collection of command line arguments as a string
  /// of text. The usage information consists of each argument's longest key and value type,
  /// enclosed in square braces for optional command line arguments. Lines are wrapped.
  /// @param[in] line_length The desired line length to use when wrapping. Must be strictly greater
  /// than zero. The recommended value is 80. The actual line length may be longer if the string of
  /// text contains very long words whose lengths exceed the desired line length.
  /// @return The string of text that contains the usage information of this collection of command
  /// line arguments.
  /// @throws std::invalid_argument if the desired line length is zero.
  [[nodiscard]] std::string usage(const std::size_t line_length) const {
    validate_line_length(line_length);
    std::string result;
    result.append(executable_path_.filename().string());
    std::apply(
        [&](const auto&... argument) {
          (..., [&] {
            result.push_back(' ');
            result.append(argument.usage());
          }());
        },
        arguments_);
    return result;
  }
 
  /// @brief Prints the options information of this collection of command line argument as a string
  /// of text. The options information consists of the list of each command line argument's keys,
  /// value type, and description.
  /// @return The string of text that contains the options information of this collection of command
  /// line arguments.
  [[nodiscard]] std::string options() const {
    return options(std::numeric_limits<std::size_t>::max());
  }
 
  /// @brief Prints the options information of this collection of command line argument as a string
  /// of text. The options information consists of the list of each command line argument's keys,
  /// value type, and description. Lines are wrapped.
  /// @param[in] line_length The desired line length to use when wrapping. Must be strictly greater
  /// than zero. The recommended value is 80. The actual line length may be longer if the string of
  /// text contains very long words whose lengths exceed the desired line length.
  /// @return The string of text that contains the options information of this collection of command
  /// line arguments.
  /// @throws std::invalid_argument if the desired line length is zero.
  [[nodiscard]] std::string options(const std::size_t line_length) const {
    validate_line_length(line_length);
    // Compute the text formatting dimensions.
    constexpr std::size_t gutter_width{2UL};
    const std::size_t maximum_first_column_width{
      (line_length - gutter_width) / static_cast<std::size_t>(2UL)};
    const std::size_t maximum_length_of_keys_with_value_types_{
      maximum_length_of_keys_with_value_type()};
    const std::size_t first_column_width{
      std::min(maximum_length_of_keys_with_value_types_, maximum_first_column_width)};
    const std::size_t second_column_width{line_length - gutter_width - first_column_width};
    // Obtain the number of command line arguments.
    constexpr std::size_t argument_count{std::tuple_size_v<decltype(arguments_)>};
    // Iterate through the command line arguments and update the resulting string of text.
    std::string result;
    std::size_t argument_index{0UL};
    std::apply(
        [&](const auto&... argument) {
          (..., [&] {
            result.append(lector::collate_and_align_left(
                argument.keys_with_value_type(), first_column_width, argument.description(),
                second_column_width));
            ++argument_index;
            if (argument_index < argument_count) {
              result.push_back('\n');
            }
          }());
        },
        arguments_);
    return result;
  }
 
  /// @brief Prints the help information of this collection of command line arguments as a string of
  /// text. The help information consists of this collection of command line arguments' title, usage
  /// information, description, options information, and notes.
  /// @return The string of text that contains the help information of this collection of command
  /// line arguments.
  [[nodiscard]] std::string help() const {
    return help(std::numeric_limits<std::size_t>::max());
  }
 
  /// @brief Prints the help information of this collection of command line arguments as a string of
  /// text. The help information consists of this collection of command line arguments' title, usage
  /// information, description, options information, and notes. Lines are wrapped.
  /// @param[in] line_length The desired line length to use when wrapping. Must be strictly greater
  /// than zero. The recommended value is 80. The actual line length may be longer if the string of
  /// text contains very long words whose lengths exceed the desired line length.
  /// @return The string of text that contains the help information of this collection of command
  /// line arguments.
  /// @throws std::invalid_argument if the desired line length is zero.
  [[nodiscard]] std::string help(const std::size_t line_length) const {
    validate_line_length(line_length);
    std::string result;
    if (configuration_.title.has_value() && !configuration_.title.value().empty()) {
      result.append(lector::wrap_and_align_left(configuration_.title.value(), line_length));
    }
    const std::string usage_{lector::wrap_and_align_left(usage(), line_length)};
    if (!usage_.empty()) {
      if (!result.empty()) {
        result.push_back('\n');
        result.push_back('\n');
      }
      result.append("Usage:\n");
      result.append(usage_);
    }
    if (configuration_.description.has_value() && !configuration_.description.value().empty()) {
      if (!result.empty()) {
        result.push_back('\n');
        result.push_back('\n');
      }
      result.append(lector::wrap_and_align_left(configuration_.description.value(), line_length));
    }
    const std::string options_{options(line_length)};
    if (!options_.empty()) {
      if (!result.empty()) {
        result.push_back('\n');
        result.push_back('\n');
      }
      result.append("Options:\n");
      result.append(options_);
    }
    if (configuration_.notes.has_value() && !configuration_.notes.value().empty()) {
      if (!result.empty()) {
        result.push_back('\n');
        result.push_back('\n');
      }
      result.append(lector::wrap_and_align_left(configuration_.notes.value(), line_length));
    }
    return result;
  }
 
  /// @brief Prints the execution of this collection of command line argument as a string of text.
  /// The execution consists of the executable path followed by each argument's longest key and
  /// corresponding parsed value, if any.
  /// @return The string of text that contains the execution of this collection of command line
  /// argument.
  [[nodiscard]] std::string execution() const {
    return execution(std::numeric_limits<std::size_t>::max());
  }
 
  /// @brief Prints the execution of this collection of command line argument as a string of text.
  /// The execution consists of the executable path followed by each argument's longest key and
  /// corresponding parsed value, if any. Lines are wrapped.
  /// @param[in] line_length The desired line length to use when wrapping. Must be strictly greater
  /// than zero. The recommended value is 80. The actual line length may be longer if the string of
  /// text contains very long words whose lengths exceed the desired line length.
  /// @return The string of text that contains the execution of this collection of command line
  /// argument.
  /// @throws std::invalid_argument if the desired line length is zero.
  [[nodiscard]] std::string execution(const std::size_t line_length) const {
    validate_line_length(line_length);
    std::string printed_execution_arguments;
    std::apply(
        [&](const auto&... argument) {
          (..., [&] {
            const std::string argument_execution{argument.execution()};
            if (!printed_execution_arguments.empty() && !argument_execution.empty()) {
              printed_execution_arguments.push_back(' ');
            }
            printed_execution_arguments.append(argument_execution);
          }());
        },
        arguments_);
    if (printed_execution_arguments.empty()) {
      return executable_path_.string();
    }
    return lector::wrap_and_align_left(
        executable_path_.string() + " " + printed_execution_arguments, line_length);
  }
 
private:
  /// @brief Default length to use when wrapping lines when printing usage information, options
  /// information, or help information as a string of text. The actual line length may be longer if
  /// the string of text contains very long words whose lengths exceed the desired line length.
  static constexpr std::size_t default_line_length_{80UL};
 
  /// @brief Data structure that contains the best matching argument for a command line argument
  /// token during parsing. The best matching argument is the argument with the longest matching
  /// key, and if there are multiple arguments with keys of the same length that match, then the
  /// best matching argument is the one that is matched by a non-inline key rather than an inline
  /// key. Used to avoid shadowing when multiple arguments have keys that are prefixes of each
  /// other, and to prefer non-inline matches over inline matches when the key lengths are equal.
  struct BestArgument final {
    /// @brief Index of this argument in the tuple of arguments. Used to identify this argument
    /// during parsing.
    std::size_t index{0UL};
 
    /// @brief Length of the longest matching key for this argument. Used to avoid shadowing when
    /// multiple arguments have keys that are prefixes of each other. For example, if one argument
    /// has the key "key" and another argument has the key "key_long", then the argument with the
    /// key "key_long" should be matched for the command line argument "key_long=value", not the
    /// argument with the key "key".
    std::size_t key_length{0UL};
 
    /// @brief Whether this argument was matched by an inline key of the form "key=value" rather
    /// than a whitespace-separated key-value pair of the form "key value". Used to prefer
    /// non-inline matches over inline matches when the key lengths are equal. For example, if one
    /// argument has the key "key" and another argument has the key "key_long", then the argument
    /// with the key "key" should be matched for the command line argument "key=value", not the
    /// argument with the key "key_long".
    bool is_inline{false};
  };
 
  /// @brief Validates that the arguments in this collection of command line arguments are
  /// consistent.
  /// @throws std::logic_error if a repeated positional argument is mixed with other positional
  /// arguments, or if the same key is duplicated across two or more arguments.
  void validate_arguments() const {
    validate_positional_arguments();
    validate_keys();
  }
 
  /// @brief Validates that this collection of command line arguments does not mix a repeated
  /// positional command line argument with other positional arguments.
  /// @throws std::logic_error if a repeated positional argument is mixed with other positional
  /// arguments.
  void validate_positional_arguments() const {
    bool has_repeated_positional_argument{false};
    std::size_t positional_argument_count{0UL};
    std::apply(
        [&](const auto&... argument) {
          (..., [&] {
            if (argument.form() == lector::Form::Positional) {
              ++positional_argument_count;
              if (argument.arity() == lector::Arity::Repeatable) {
                has_repeated_positional_argument = true;
              }
            }
          }());
        },
        arguments_);
    if (has_repeated_positional_argument
        && positional_argument_count >= static_cast<std::size_t>(2UL)) {
      throw std::logic_error(
          "A repeated positional argument cannot be mixed with any other positional arguments.");
    }
  }
 
  /// @brief Validates that the same key is never duplicated across two or more arguments.
  /// @throws std::logic_error if the same key is duplicated across two or more arguments.
  void validate_keys() const {
    std::unordered_set<std::string> unique_keys;
    std::apply(
        [&](const auto&... argument) {
          (..., [&] {
            for (const std::string& key : argument.keys()) {
              const std::pair<std::unordered_set<std::string>::const_iterator, bool> result{
                unique_keys.insert(key)};
              if (!result.second) {
                throw std::logic_error("Duplicate key '" + key + "' across two arguments.");
              }
            }
          }());
        },
        arguments_);
  }
 
  /// @brief Validates that a specified line length is strictly greater than zero.
  /// @param[in] line_length The desired line length to use when wrapping. Must be strictly greater
  /// than zero.
  /// @throws std::invalid_argument if the desired line length is zero.
  static void validate_line_length(const std::size_t line_length) {
    if (line_length <= static_cast<std::size_t>(0UL)) {
      throw std::invalid_argument("Invalid line length. Must be strictly greater than zero.");
    }
  }
 
  /// @brief Parses the executable path from argc and argv.
  /// @param[in] argc The number of command line arguments, including the executable path.
  /// @param[in] argv The array of C-strings that represents the command line arguments, starting
  /// with the executable path.
  void parse_executable_path(const int argc, char* argv[]) {
    if (argc > 0) {
      executable_path_ = argv[0];
    }
  }
 
  /// @brief Parses argc and argv, except for the executable path, and attempts to match them to the
  /// named arguments. Starts at the second argument in argv. Remaining arguments that could not be
  /// matched to named arguments are treated as positional arguments and returned.
  /// @param[in] argc The number of command line arguments, including the executable path.
  /// @param[in] argv The array of C-strings that represents the command line arguments, starting
  /// with the executable path.
  /// @return Collection of the remaining command line arguments that could not be matched to named
  /// arguments, which are treated as positional arguments.
  /// @throws std::invalid_argument if an invalid, unknown, duplicate, or missing argument is
  /// encountered.
  [[nodiscard]] std::vector<std::string_view> parse_named_arguments(const int argc, char* argv[]) {
    std::vector<std::string_view> positional_tokens;
    const std::size_t count{static_cast<std::size_t>(argc)};
    for (std::size_t argv_index{1UL}; argv_index < count; ++argv_index) {
      const std::string_view token{argv[argv_index]};
      const std::optional<BestArgument> best_argument{find_best_argument(token)};
      if (best_argument.has_value()) {
        std::size_t current_index{0UL};
        std::apply(
            [&](auto&... argument) {
              (..., [&] {
                if (current_index == best_argument->index) {
                  populate_argument(argument, best_argument.value(), argc, argv, argv_index);
                }
                ++current_index;
              }());
            },
            arguments_);
      } else {
        // If no named argument key matches the current argv token, treat it as the value of a
        // positional argument.
        positional_tokens.push_back(token);
      }
    }
    return positional_tokens;
  }
 
  /// @brief Parses the remaining command line arguments that could not be matched to named
  /// arguments as positional arguments.
  /// @param[in] positional_tokens Collection of the remaining command line arguments that could not
  /// be matched to named arguments, which are treated as positional arguments.
  /// @throws std::invalid_argument if too many positional arguments are provided or if a positional
  /// argument cannot be parsed.
  void parse_positional_arguments(const std::vector<std::string_view>& positional_tokens) {
    std::size_t positional_token_index{0UL};
    std::apply(
        [&](auto&... argument) {
          (..., [&] {
            if (argument.form() == lector::Form::Positional) {
              using Type = typename std::decay_t<decltype(argument)>::ValueType;
              if (argument.arity() == lector::Arity::Singular) {
                if (positional_token_index < positional_tokens.size()) {
                  const std::string raw_value{positional_tokens.at(positional_token_index)};
                  const std::optional<Type> parsed_value{lector::parse<Type>(raw_value)};
                  if (parsed_value.has_value()) {
                    argument.set_parsed_value(parsed_value.value());
                  } else {
                    throw std::invalid_argument("Invalid value '" + raw_value + "' for argument '"
                                                + argument.options() + "'.");
                  }
                  ++positional_token_index;
                }
              } else {
                // Repeatable arity: consume all remaining tokens.
                while (positional_token_index < positional_tokens.size()) {
                  const std::string raw_value{positional_tokens.at(positional_token_index)};
                  const std::optional<Type> parsed_value{lector::parse<Type>(raw_value)};
                  if (parsed_value.has_value()) {
                    argument.set_parsed_value(parsed_value.value());
                  } else {
                    throw std::invalid_argument("Invalid value '" + raw_value + "' for argument '"
                                                + argument.options() + "'.");
                  }
                  ++positional_token_index;
                }
              }
            }
          }());
        },
        arguments_);
    validate_all_positional_tokens_matched(positional_tokens, positional_token_index);
  }
 
  /// @brief Finds the best matching argument for a command line argument token.
  /// @param[in] token The command line argument token to match.
  /// @return The best matching argument.
  /// @throws std::invalid_argument if an unknown argument is encountered.
  [[nodiscard]] std::optional<BestArgument> find_best_argument(const std::string_view token) const {
    std::optional<BestArgument> best;
    std::size_t argument_index{0UL};
    std::apply(
        [&](const auto&... argument) {
          (..., [&] {
            for (const std::string& argument_key : argument.keys()) {
              const std::optional<BestArgument> exact_match{
                try_exact_match(token, argument_index, argument_key)};
              if (exact_match.has_value()) {
                if (!best.has_value() || exact_match->key_length > best->key_length
                    || (exact_match->key_length == best->key_length && best->is_inline)) {
                  best = exact_match;
                }
                continue;
              }
              const std::optional<BestArgument> inline_match{
                try_inline_match<decltype(argument)>(token, argument_index, argument_key)};
              if (inline_match.has_value()
                  && (!best.has_value() || inline_match->key_length > best->key_length)) {
                best = inline_match;
              }
            }
            ++argument_index;
          }());
        },
        arguments_);
    return best;
  }
 
  /// @brief Checks whether a token is the exact match of an argument's key.
  /// @param[in] token The token to check.
  /// @param[in] argument_index The index of the argument that has the key.
  /// @param[in] argument_key The argument key against which to compare.
  /// @return A populated lector::Arguments::BestArgument data structure if the specified token is
  /// an exact match for the key, or std::nullopt otherwise.
  [[nodiscard]] static std::optional<BestArgument> try_exact_match(
      const std::string_view token, const std::size_t argument_index,
      const std::string_view argument_key) noexcept {
    if (token == argument_key) {
      return BestArgument{argument_index, argument_key.size(), false};
    }
    return std::nullopt;
  }
 
  /// @brief Checks whether a token contains an inline match of an argument's key of the form
  /// "key=value".
  /// @tparam SingularArgument The type of the argument that has the key to be used in the
  /// comparison.
  /// @param[in] token The token to check.
  /// @param[in] argument_index The index of the argument that has the key to be used in the
  /// comparison.
  /// @param[in] argument_key The argument key against which to compare.
  /// @return A populated lector::Arguments::BestArgument data structure if the specified token
  /// contains an inline match for the key, or std::nullopt otherwise.
  template <typename SingularArgument>
  [[nodiscard]] static std::optional<BestArgument> try_inline_match(
      const std::string_view token, const std::size_t argument_index,
      const std::string_view argument_key) noexcept {
    using ArgumentType = typename std::decay_t<SingularArgument>::ValueType;
    // Inline matching is strictly disabled for boolean arguments because they are key-only flags
    // that do not have values.
    if constexpr (!std::is_same_v<ArgumentType, bool>) {
      if (token.size() > argument_key.size()
          && token.compare(0, argument_key.size(), argument_key) == 0
          && token[argument_key.size()] == '=') {
        return BestArgument{argument_index, argument_key.size(), true};
      }
    }
    return std::nullopt;
  }
 
  /// @brief Populates an argument with its parsed value.
  /// @tparam ArgumentType The type of the argument to be populated.
  /// @param[in,out] argument The argument to be populated.
  /// @param[in] best_argument The lector::Arguments::BestArgument data structure that corresponds
  /// to the argument to be populated.
  /// @param[in] argc The number of command line arguments, including the executable path.
  /// @param[in] argv The array of C-strings that represents the command line arguments, starting
  /// with the executable path.
  /// @param[in,out] argv_index The index of the argument in the array of C-string command line
  /// arguments whose value is to be extracted and used to populate the argument.
  /// @throws std::invalid_argument if the parsed value is invalid for this argument type.
  template <typename ArgumentType>
  static void populate_argument(ArgumentType& argument, const BestArgument& best_argument,
                                const int argc, char* argv[], std::size_t& argv_index) {
    using Type = typename std::decay_t<ArgumentType>::ValueType;
    if constexpr (std::is_same_v<Type, bool>) {
      // Boolean arguments are key-only flags; their presence implies true.
      argument.set_parsed_value(true);
    } else {
      // This is a non-boolean argument. Extract and parse its value.
      const std::string raw_value{
        extract_raw_value(best_argument, argument.options(), argc, argv, argv_index)};
      const std::optional<Type> parsed_value{lector::parse<Type>(raw_value)};
      if (parsed_value.has_value()) {
        argument.set_parsed_value(parsed_value.value());
      } else {
        throw std::invalid_argument(
            "Invalid value '" + raw_value + "' for argument '" + argument.options() + "'.");
      }
    }
  }
 
  /// @brief Extracts the raw string value from an argv token for a non-boolean best argument.
  /// @param[in] best_argument The best argument.
  /// @param[in] best_argument_options The options string of the best argument, for printing to an
  /// error message if needed.
  /// @param[in] argc The number of command line arguments, including the executable path.
  /// @param[in] argv The array of C-strings that represents the command line arguments, starting
  /// with the executable path.
  /// @param[in,out] argv_index The index of the argument in the array of C-string command line
  /// arguments whose raw string value is to be extracted.
  /// @return The extracted raw string value.
  /// @throws std::invalid_argument if the command line arguments are missing the value for this
  /// best argument.
  [[nodiscard]] static std::string extract_raw_value(
      const BestArgument& best_argument, const std::string& best_argument_options, const int argc,
      char* argv[], std::size_t& argv_index) {
    const std::string_view token{argv[argv_index]};
    if (best_argument.is_inline) {
      // The token contains an inline value of the form "key=value". Extract the last portion of the
      // token.
      return std::string{token.substr(best_argument.key_length + 1)};
    }
    if (argv_index + 1 < static_cast<std::size_t>(argc)) {
      // The token is a standalone value of the form "key", and the next token is of the form
      // "value". Advance the argv index to consume the next argv element that contains the value.
      ++argv_index;
      return std::string{argv[argv_index]};
    }
    throw std::invalid_argument("Missing value for argument '" + best_argument_options + "'.");
  }
 
  /// @brief Validates that all raw positional tokens have been consumed by positional command line
  /// arguments.
  /// @param[in] positional_tokens The raw positional command line tokens.
  /// @param[in] positional_token_index The parsed index in the collection of raw positional command
  /// line tokens.
  /// @throws std::invalid_argument if any raw positional command line tokens were not consumed by
  /// positional command line arguments.
  void validate_all_positional_tokens_matched(
      const std::vector<std::string_view>& positional_tokens,
      const std::size_t positional_token_index) {
    if (positional_token_index < positional_tokens.size()) {
      std::string unexpected_tokens;
      for (std::size_t unexpected_token_index{positional_token_index};
           unexpected_token_index < positional_tokens.size(); ++unexpected_token_index) {
        if (!unexpected_tokens.empty()) {
          unexpected_tokens.append(", ");
        }
        unexpected_tokens.push_back('\'');
        unexpected_tokens.append(std::string{positional_tokens.at(unexpected_token_index)});
        unexpected_tokens.push_back('\'');
      }
      throw std::invalid_argument("Unexpected command line tokens: " + unexpected_tokens + ".");
    }
  }
 
  /// @brief Computes and returns the maximum length of the printed keys and value type across all
  /// arguments in this collection of command line arguments.
  /// @return The maximum length of the printed keys and value type across all arguments in this
  /// collection.
  [[nodiscard]] std::size_t maximum_length_of_keys_with_value_type() const {
    std::size_t maximum_length{0UL};
    std::apply(
        [&](const auto&... argument) {
          (..., [&] {
            const std::size_t length{lector::count_code_points(argument.keys_with_value_type())};
            maximum_length = std::max(maximum_length, length);
          }());
        },
        arguments_);
    return maximum_length;
  }
 
  /// @brief Configuration of the help information of this collection of command line arguments.
  lector::Configuration configuration_{};
 
  /// @brief Variadic collection of command line arguments.
  std::tuple<ArgumentTypes...> arguments_;
 
  /// @brief Executable path of this collection of command line arguments. If the command line
  /// arguments have not yet been parsed from argc and argv, this path is empty.
  std::filesystem::path executable_path_;
};
 
}  // namespace lector
 
#endif  // LECTOR_ARGUMENTS_HPP