YT-CPPAP-51: Improve string value handling and argument flag detection

- Aligned argument value setting to use direct `value_type` object initialization from `std::string` values if possible (arguments, the value type of which cannot be constructed from `std::string` will use the `istream>>` operator as in previous versions)

  NOTE: This fixes the issue, where passing a mulit-word optional argument's value, e.g.
    `./program --option "single value with spaces"`
  would result in storing only the first word of the value ("single" in this case)

- Altered the behavior of unknown argument flag handling: a `parsing_failre` exception is thrown instead of handling it as a value argument token

- Added the `AP_UNKNOWN_FLAGS_AS_VALUES` option support: using this option changes the unknown argument flag handling strategy back to treating it as a value

- Modified the test building to compile each test file into a separate executable registered with CTest

- Corrected the argument value type requirements description in the tutorial document

Author: SpectraL519

.github/workflows/clang.yaml

@@ -29,12 +29,11 @@ jobs:
           cmake -B build -DBUILD_TESTS=ON -DCMAKE_CXX_COMPILER=$CXX -DCMAKE_C_COMPILER=$CC
         continue-on-error: false
 
-      - name: Build test executable
+      - name: Build tests
         run: |
-          cd build && make -j 4
+          cmake --build build/ -j 4
         continue-on-error: false
 
       - name: Run tests
         run: |
-          ./build/tests/run
-        continue-on-error: false
+          ctest --test-dir build/tests/ -V

.github/workflows/gpp.yaml

@@ -29,11 +29,11 @@ jobs:
           cmake -B build -DBUILD_TESTS=ON -DCMAKE_CXX_COMPILER=$CXX -DCMAKE_C_COMPILER=$CC
         continue-on-error: false
 
-      - name: Build test executable
+      - name: Build tests
         run: |
-          cd build && make -j 4
+          cmake --build build/ -j 4
         continue-on-error: false
 
       - name: Run tests
         run: |
-          ./build/tests/run
+          ctest --test-dir build/tests/ -V

.gitignore

@@ -4,6 +4,7 @@
 # build files
 *build*/
 *.exe
+Testing/
 
 # documentation files
 /documentation

CMakeLists.txt

@@ -7,7 +7,7 @@ else()
 endif()
 
 project(cpp-ap
-    VERSION 2.3.1
+    VERSION 2.4.0
     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.3.1
+PROJECT_NUMBER         = 2.4.0
 
 # 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

docs/dev_notes.md

@@ -12,22 +12,24 @@
 
 ```shell
 cmake -B build -DBUILD_TESTS=ON
-cd build
-make # -j <n>
+cmake --build build/ # -j <njobs>
 ```
 
-This will build the test executable `run` in the `<project-root>/build/tests` directory.
+This will build each test file as a separate executable in the `build/tests/` directory.
 
 ### Run the tests
 
+You can run tests from each test file separately with:
+
 ```shell
-cd build
-./tests/run # -ts=<test-suite-name>
+./build/tests/<test-name>
 ```
 
-> [!NOTE]
->
-> Test suites in the project have the same names as the files they're in except for the `test_extarnal_libs_config.cpp` file which defines the `test_doctest_config` test suite.
+To execute all tests at once run:
+
+```shell
+ctest --test-dir build/tests/ # -V (to capture output from each test executable)
+```
 
 <br />
 <br />

docs/tutorial.md

@@ -106,16 +106,19 @@ or
 parser.add_<positional/optional>_argument<value_type>("argument", "a");
 ```
 
-> [!NOTE]
+> [!IMPORTANT]
 >
 > The library supports any argument value types which meet the following requirements:
 >
-> - The `std::ostream& operator<<` is overloaded for the value type
-> - The value type has a copy constructor and an assignment operator
+> - The type is [constructible from](https://en.cppreference.com/w/cpp/concepts/constructible_from) `const std::string&` or the stream extraction operator - `std::istream& operator>>` is defined for the type.
+>
+>    **IMPORTANT:** The argument parser will always use direct initialization from `std::string` and will use the extraction operator only if an argument's value type cannot be initialized from `std::string`.
+>
+> - The type satisfies the [`std::semiregular`](https://en.cppreference.com/w/cpp/concepts/semiregular.html) concept - is default initializable and copyable.
 
-> [!IMPORTANT]
+> [!NOTE]
 >
-> If the `value_type` is not provided, `std::string` will be used.
+> The default value type of any argument is `std::string`.
 
 You can also add boolean flags:
 
@@ -633,6 +636,35 @@ The `argument_parser` class also defines the `void parse_args(int argc, char* ar
 > parse_args(std::span(argv + 1, argc - 1));
 > ```
 
+> [!WARNING]
+>
+> By default the `argument_parser` class treats *all\** command-line arguments beggining with a `--` or `-` prefix as optional argument flags and if the flag's value does not match any of the specified arguments, then such flag is considered *unknown* and an exception will be thrown.
+>
+> *\** If a command-line argument begins with a flag prefix, but contains whitespaces (e.g. `"--flag value"`), then it is treated as a value and not a flag.
+>
+> This behavior can be altered so that the unknown argument flags will be treated as values, not flags.
+>
+> Example:
+> ```cpp
+> parser.add_optional_argument("option", "o");
+> parser.try_parse_args(argc, argv);
+> std::cout << "option: " << parser.value("option");
+>
+> /*
+> ./program --option --unknown-flag
+> option: --unknown-flag
+> ```
+>
+> To do this add the following in you `CMakeLists.txt` file:
+> ```cmake
+> target_compile_definitions(cpp-ap-2 PRIVATE AP_UNKNOWN_FLAGS_AS_VALUES)
+> ```
+> or simply add:
+> ```cpp
+> #define AP_UNKNOWN_FLAGS_AS_VALUES
+> ```
+> before the `#include <ap/argument_parser.hpp>` statement.
+
 > [!TIP]
 >
 > The `parse_args` function may throw an `ap::argument_parser_exception` (specifically the `ap::parsing_failure` derived exception) if the provided command-line arguments do not match the expected configuration. To simplify error handling, the `argument_parser` class provides `try_parse_args` methods, which automatically catch these exceptions, print the error message, and exit with a failure status.
@@ -766,7 +798,7 @@ int main(int argc, char* argv[]) {
 
 > [!IMPORTANT]
 >
-> The parser behaviour depends on the argument definitions. The argument parameters are described int the [Argument parameters](#argument-parameters) section.
+> The parser's behavior depends on the argument definitions - see [Argument Parameters](#argument-parameters) section.
 
 <br/>
 <br/>
@@ -778,14 +810,14 @@ You can retrieve the argument's value with:
 
 ```cpp
 (const) auto value = parser.value<value_type>("argument_name"); // (1)
-(const) auto value = parser.value_or<value_type>("argument_name", default_value); // (2)
+(const) auto value = parser.value_or<value_type>("argument_name", fallback_value); // (2)
 ```
 
 1. This will return the value parsed for the given argument.
 
     For optional arguments this will return the argument's predefined value if no value has been parsed. Additionaly, if more than one value has been parsed for an optional argument, this function will return the first parsed value.
 
-2. When a value has been parsed for the argument, the behaviour is the same as in case **(1)**. Otherwise, this will return `value_type{std::forward<U>(default_value)}` (where `U` is the deducted type of `default_value`), if:
+2. When a value has been parsed for the argument, the behavior is the same as in case **(1)**. Otherwise, this will return `value_type{std::forward<U>(fallback_value)}` (where `U` is the deducted type of `fallback_value`), if:
 
     - There is no value parsed for a positional argument
     - There is no parsed values and no predefined values for an optional arrument

include/ap/argument/optional.hpp

@@ -207,12 +207,10 @@ class optional : public detail::argument_base {
 
     /**
      * @param verbose The verbosity mode value.
-     * @param flag_char The character used for the argument flag prefix.
      * @return An argument descriptor object for the argument.
      */
-    [[nodiscard]] detail::argument_descriptor desc(const bool verbose, const char flag_char)
-        const noexcept override {
-        detail::argument_descriptor desc(this->_name.str(flag_char), this->_help_msg);
+    [[nodiscard]] detail::argument_descriptor desc(const bool verbose) const noexcept override {
+        detail::argument_descriptor desc(this->_name.str(), this->_help_msg);
 
         if (not verbose)
             return desc;
@@ -265,8 +263,13 @@ class optional : public detail::argument_base {
             throw parsing_failure::invalid_nvalues(this->_name, std::weak_ordering::greater);
 
         value_type value;
-        if (not (std::istringstream(str_value) >> value))
-            throw parsing_failure::invalid_value(this->_name, str_value);
+        if constexpr (detail::c_trivially_readable<value_type>) {
+            value = value_type(str_value);
+        }
+        else {
+            if (not (std::istringstream(str_value) >> value))
+                throw parsing_failure::invalid_value(this->_name, str_value);
+        }
 
         if (not detail::is_valid_choice(value, this->_choices))
             throw parsing_failure::invalid_choice(this->_name, str_value);

include/ap/argument/positional.hpp

@@ -156,12 +156,9 @@ class positional : public detail::argument_base {
 
     /**
      * @param verbose The verbosity mode value.
-     * @param flag_char The character used for the argument flag prefix.
      * @return An argument descriptor object for the argument.
      */
-    [[nodiscard]] detail::argument_descriptor desc(
-        const bool verbose, [[maybe_unused]] const char flag_char
-    ) const noexcept override {
+    [[nodiscard]] detail::argument_descriptor desc(const bool verbose) const noexcept override {
         detail::argument_descriptor desc(this->_name.str(), this->_help_msg);
 
         if (not verbose)
@@ -210,8 +207,13 @@ class positional : public detail::argument_base {
             throw parsing_failure::value_already_set(this->_name);
 
         value_type value;
-        if (not (std::istringstream(str_value) >> value))
-            throw parsing_failure::invalid_value(this->_name, str_value);
+        if constexpr (detail::c_trivially_readable<value_type>) {
+            value = value_type(str_value);
+        }
+        else {
+            if (not (std::istringstream(str_value) >> value))
+                throw parsing_failure::invalid_value(this->_name, str_value);
+        }
 
         if (not detail::is_valid_choice(value, this->_choices))
             throw parsing_failure::invalid_choice(this->_name, str_value);