YT-CPPAP-52: Optional arguments with secondary names only

- Aligned the `argument_name` class to store both primary and secondary names as optionals
- Added the `argument_name_discriminator` enum for the purpose of argument initialization with specific name member being set
- Aligned the `add_optional_argument` and `add_flag` methods of `argument_parser` to take a discriminator member, specifying which name member should be set for the new argument

Author: SpectraL519

CMakeLists.txt

@@ -7,7 +7,7 @@ else()
 endif()
 
 project(cpp-ap
-    VERSION 2.5.2
+    VERSION 2.5.3
     DESCRIPTION "Command-line argument parser for C++20"
     HOMEPAGE_URL "https://github.com/SpectraL519/cpp-ap"
     LANGUAGES CXX

Doxyfile

@@ -48,7 +48,7 @@ PROJECT_NAME           = CPP-AP
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2.5.2
+PROJECT_NUMBER         = 2.5.3
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

MODULE.bazel

@@ -1,4 +1,4 @@
 module(
     name = "cpp-ap",
-    version = "2.5.2",
+    version = "2.5.3",
 )

docs/tutorial.md

@@ -178,6 +178,15 @@ parser.add_optional_argument<bool>("disable_another_option", "dao")
 */
 ```
 
+> [!NOTE]
+>
+> While passing a primary name is required for creating positional arguments, optional arguments (and flags) can be initialized using only a secondary name as follows:
+>
+> ```cpp
+> parser.add_optional_argument("a", ap::n_secondary);
+> parser.add_flag("f", ap::n_secondary);
+> ```
+
 <br/>
 <br/>
 <br/>

include/ap/argument/positional.hpp

@@ -276,7 +276,7 @@ class positional : public detail::argument_base {
      */
     [[nodiscard]] const std::vector<std::any>& values() const override {
         throw std::logic_error(
-            std::format("Positional argument `{}` has only 1 value.", this->_name.primary)
+            std::format("Positional argument `{}` has only 1 value.", this->_name.str())
         );
     }
 

include/ap/argument_parser.hpp

@@ -142,10 +142,10 @@ class argument_parser {
      * \todo Check forbidden characters (after adding the assignment character).
      */
     template <detail::c_argument_value_type T = std::string>
-    argument::positional<T>& add_positional_argument(std::string_view primary_name) {
+    argument::positional<T>& add_positional_argument(const std::string_view primary_name) {
         this->_verify_arg_name_pattern(primary_name);
 
-        const detail::argument_name arg_name(primary_name);
+        const detail::argument_name arg_name(std::make_optional<std::string>(primary_name));
         if (this->_is_arg_name_used(arg_name))
             throw invalid_configuration::argument_name_used(arg_name);
 
@@ -165,12 +165,15 @@ class argument_parser {
      */
     template <detail::c_argument_value_type T = std::string>
     argument::positional<T>& add_positional_argument(
-        std::string_view primary_name, std::string_view secondary_name
+        const std::string_view primary_name, const std::string_view secondary_name
     ) {
         this->_verify_arg_name_pattern(primary_name);
         this->_verify_arg_name_pattern(secondary_name);
 
-        const detail::argument_name arg_name(primary_name, secondary_name);
+        const detail::argument_name arg_name{
+            std::make_optional<std::string>(primary_name),
+            std::make_optional<std::string>(secondary_name)
+        };
         if (this->_is_arg_name_used(arg_name))
             throw invalid_configuration::argument_name_used(arg_name);
 
@@ -181,17 +184,27 @@ class argument_parser {
     /**
      * @brief Adds a positional argument to the parser's configuration.
      * @tparam T Type of the argument value.
-     * @param primary_name The primary name of the argument.
+     * @param name The name of the argument.
+     * @param name_discr The discriminator value specifying whether the given name should be treated as primary or secondary.
      * @return Reference to the added optional argument.
      * @throws ap::invalid_configuration
      *
      * \todo Check forbidden characters (after adding the assignment character).
      */
     template <detail::c_argument_value_type T = std::string>
-    argument::optional<T>& add_optional_argument(std::string_view primary_name) {
-        this->_verify_arg_name_pattern(primary_name);
-
-        const detail::argument_name arg_name(primary_name, std::nullopt, this->_flag_prefix_char);
+    argument::optional<T>& add_optional_argument(
+        const std::string_view name,
+        const detail::argument_name_discriminator name_discr = n_primary
+    ) {
+        this->_verify_arg_name_pattern(name);
+
+        const auto arg_name =
+            name_discr == n_primary
+                ? detail::
+                      argument_name{std::make_optional<std::string>(name), std::nullopt, this->_flag_prefix_char}
+                : detail::argument_name{
+                      std::nullopt, std::make_optional<std::string>(name), this->_flag_prefix_char
+                  };
         if (this->_is_arg_name_used(arg_name))
             throw invalid_configuration::argument_name_used(arg_name);
 
@@ -211,12 +224,16 @@ class argument_parser {
      */
     template <detail::c_argument_value_type T = std::string>
     argument::optional<T>& add_optional_argument(
-        std::string_view primary_name, std::string_view secondary_name
+        const std::string_view primary_name, const std::string_view secondary_name
     ) {
         this->_verify_arg_name_pattern(primary_name);
         this->_verify_arg_name_pattern(secondary_name);
 
-        const detail::argument_name arg_name(primary_name, secondary_name, this->_flag_prefix_char);
+        const detail::argument_name arg_name(
+            std::make_optional<std::string>(primary_name),
+            std::make_optional<std::string>(secondary_name),
+            this->_flag_prefix_char
+        );
         if (this->_is_arg_name_used(arg_name))
             throw invalid_configuration::argument_name_used(arg_name);
 
@@ -227,12 +244,16 @@ class argument_parser {
     /**
      * @brief Adds a boolean flag argument (an optional argument with `value_type = bool`) to the parser's configuration.
      * @tparam StoreImplicitly A boolean value used as the `implicit_value` parameter of the argument.
-     * @param primary_name The primary name of the flag.
+     * @param name The primary name of the flag.
+     * @param name_discr The discriminator value specifying whether the given name should be treated as primary or secondary.
      * @return Reference to the added boolean flag argument.
      */
     template <bool StoreImplicitly = true>
-    argument::optional<bool>& add_flag(std::string_view primary_name) {
-        return this->add_optional_argument<bool>(primary_name)
+    argument::optional<bool>& add_flag(
+        const std::string_view name,
+        const detail::argument_name_discriminator name_discr = n_primary
+    ) {
+        return this->add_optional_argument<bool>(name, name_discr)
             .default_value(not StoreImplicitly)
             .implicit_value(StoreImplicitly)
             .nargs(0ull);
@@ -247,7 +268,7 @@ class argument_parser {
      */
     template <bool StoreImplicitly = true>
     argument::optional<bool>& add_flag(
-        std::string_view primary_name, std::string_view secondary_name
+        const std::string_view primary_name, const std::string_view secondary_name
     ) {
         return this->add_optional_argument<bool>(primary_name, secondary_name)
             .default_value(not StoreImplicitly)

include/ap/detail/argument_name.hpp

@@ -12,7 +12,9 @@
 #include <string>
 #include <string_view>
 
-namespace ap::detail {
+namespace ap {
+
+namespace detail {
 
 /// @brief Structure holding the argument's name.
 struct argument_name {
@@ -39,11 +41,17 @@ struct argument_name {
      * @param flag_char The flag character (used for optional argument names).
      */
     argument_name(
-        std::string_view primary,
-        std::optional<std::string_view> secondary = std::nullopt,
+        std::optional<std::string> primary,
+        std::optional<std::string> secondary = std::nullopt,
         std::optional<char> flag_char = std::nullopt
     )
-    : primary(primary), secondary(std::move(secondary)), flag_char(std::move(flag_char)) {}
+    : primary(std::move(primary)),
+      secondary(std::move(secondary)),
+      flag_char(std::move(flag_char)) {
+        if (not (this->primary or this->secondary))
+            throw std::logic_error("An argument name cannot be empty! At least one of "
+                                   "primary/secondary must be specified");
+    }
 
     /// @brief Class destructor.
     ~argument_name() = default;
@@ -54,13 +62,7 @@ struct argument_name {
      * @return Equality of argument names.
      */
     bool operator==(const argument_name& other) const noexcept {
-        if (not (this->secondary and other.secondary) and (this->secondary or other.secondary))
-            return false; // only one of the compared argument names has a secondary name
-
-        if (this->primary != other.primary)
-            return false;
-
-        return this->secondary ? this->secondary.value() == other.secondary.value() : true;
+        return this->primary == other.primary and this->secondary == other.secondary;
     }
 
     /**
@@ -73,11 +75,11 @@ struct argument_name {
         const noexcept {
         switch (m_type) {
         case m_any:
-            return this->match_primary(arg_name) or this->match_secondary(arg_name);
+            return this->primary == arg_name or this->secondary == arg_name;
         case m_primary:
-            return this->match_primary(arg_name);
+            return this->primary == arg_name;
         case m_secondary:
-            return this->match_secondary(arg_name);
+            return this->secondary == arg_name;
         }
 
         return false;
@@ -92,7 +94,7 @@ struct argument_name {
     [[nodiscard]] bool match(
         const argument_name& arg_name, [[maybe_unused]] const match_type m_type = m_any
     ) const noexcept {
-        if (this->match(arg_name.primary))
+        if (arg_name.primary and this->match(arg_name.primary.value()))
             return true;
 
         if (arg_name.secondary)
@@ -101,34 +103,21 @@ struct argument_name {
         return false;
     }
 
-    /**
-     * @brief Matches the given string to the primary name of an argument_name instance.
-     * @param arg_name The name string to match.
-     * @return True if name is equal to either the primary name of the argument_name instance.
-     */
-    [[nodiscard]] bool match_primary(std::string_view arg_name) const noexcept {
-        return arg_name == this->primary;
-    }
-
-    /**
-     * @brief Matches the given string to the secondary name of an argument_name instance.
-     * @param arg_name The name string to match.
-     * @return True if name is equal to either the secondary name of the argument_name instance.
-     */
-    [[nodiscard]] bool match_secondary(std::string_view arg_name) const noexcept {
-        return this->secondary and arg_name == this->secondary.value();
-    }
-
     /**
      * @brief Get a string representation of the argument_name.
      * @param flag_char The character used for the argument flag prefix.
      */
     [[nodiscard]] std::string str() const noexcept {
         // if flag_char = nullopt, then the fallback character doesn't matter - the string will be empty
         const std::string fc(this->flag_char.has_value(), this->flag_char.value_or(char()));
-        return this->secondary
-                 ? std::format("{}{}{}, {}{}", fc, fc, this->primary, fc, this->secondary.value())
-                 : std::format("{}{}{}", fc, fc, this->primary);
+
+        std::string primary_str =
+            this->primary ? std::format("{}{}{}", fc, fc, this->primary.value()) : "";
+        std::string separator = this->primary and this->secondary ? ", " : "";
+        std::string secondary_str =
+            this->secondary ? std::format("{}{}", fc, this->secondary.value()) : "";
+
+        return std::format("{}{}{}", primary_str, separator, secondary_str);
     }
 
     /**
@@ -142,9 +131,23 @@ struct argument_name {
         return os;
     }
 
-    const std::string primary; ///< The primary name of the argument.
+    const std::optional<std::string> primary; ///< The primary name of the argument.
     const std::optional<std::string> secondary; ///< The optional (short) name of the argument.
     const std::optional<char> flag_char; ///< The flag character (used for optional argument names).
 };
 
-} // namespace ap::detail
+/**
+ * @brief Argument name member discriminator.
+ *
+ * This discriminator type is used in the argument initializing methods of the `argument_parser` class.
+ */
+enum class argument_name_discriminator : bool {
+    n_primary, ///< Represents the primary name (used with a long flag prefix --).
+    n_secondary ///< Represents the secondary name (used with a short flag prefix --).
+};
+
+} // namespace detail
+
+using enum detail::argument_name_discriminator;
+
+} // namespace ap

tests/include/argument_parser_test_fixture.hpp

@@ -98,13 +98,13 @@ struct argument_parser_test_fixture {
     void add_arguments(std::size_t n_positional_args, std::size_t n_optional_args) {
         for (std::size_t i = 0ull; i < n_positional_args; ++i) {
             const auto arg_name = init_arg_name(i);
-            sut.add_positional_argument<T>(arg_name.primary, arg_name.secondary.value());
+            sut.add_positional_argument<T>(arg_name.primary.value(), arg_name.secondary.value());
         }
 
         for (std::size_t i = 0ull; i < n_optional_args; ++i) {
             const auto arg_idx = n_positional_args + i;
             const auto arg_name = init_arg_name(arg_idx);
-            sut.add_optional_argument<T>(arg_name.primary, arg_name.secondary.value());
+            sut.add_optional_argument<T>(arg_name.primary.value(), arg_name.secondary.value());
         }
     }
 
@@ -119,9 +119,9 @@ struct argument_parser_test_fixture {
 
         for (std::size_t i = 0ull; i < n_optional_args; ++i) {
             const auto arg_idx = n_positional_args + i;
-            arg_tokens.push_back(
-                argument_token{argument_token::t_flag_primary, init_arg_name(arg_idx).primary}
-            );
+            arg_tokens.push_back(argument_token{
+                argument_token::t_flag_primary, init_arg_name(arg_idx).primary.value()
+            });
             arg_tokens.push_back(argument_token{argument_token::t_value, init_arg_value(arg_idx)});
         }