YT-CPPAP-46: Add compound argument flags support

Modified the command-line tokenization logic to try to split unknown secondary flag arguments into multiple secondary argument flag tokens (one for each character of the unknown flag).

Example: If the program defines an argument with a secondary name `v`, then `-vvv` would be equivalent to `-v -v -v`, unless the program also defines a `-vvv` argument.

Additional:
- Added support for declaring the program version
- Optimized argument lookup during argument tokenization and parsing stages

Author: SpectraL519

CMakeLists.txt

@@ -7,7 +7,7 @@ else()
 endif()
 
 project(cpp-ap
-    VERSION 2.5.3
+    VERSION 2.6.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.5.3
+PROJECT_NUMBER         = 2.6.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

MODULE.bazel

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

README.md

@@ -56,6 +56,8 @@ Command-line argument parser for C++20
   - [Argument Parameters](/docs/tutorial.md#argument-parameters)
   - [Default Arguments](/docs/tutorial.md#default-arguments)
   - [Parsing Arguments](/docs/tutorial.md#parsing-arguments)
+    - [Argument Parsing Rules](/docs/tutorial.md#argument-parsing-rules)
+    - [Compound Arguments](/docs/tutorial.md#compound-arguments)
   - [Retrieving Argument Values](/docs/tutorial.md#retrieving-argument-values)
   - [Examples](/docs/tutorial.md#examples)
 - [Dev notes](/docs/dev_notes.md#dev-notes)

docs/tutorial.md

@@ -10,6 +10,8 @@
 - [Predefined Parameter Values](#predefined-parameter-values)
 - [Default Arguments](#default-arguments)
 - [Parsing Arguments](#parsing-arguments)
+  - [Argument Parsing Rules](#argument-parsing-rules)
+  - [Compound Arguments](#compound-arguments)
 - [Retrieving Argument Values](#retrieving-argument-values)
 - [Examples](#examples)
 
@@ -103,17 +105,34 @@ To use the argument parser in your code you need to use the `ap::argument_parser
 
 The parameters you can specify for a parser's instance are:
 
-- Program name and description - used in the parser's configuration output (`std::cout << parser`).
+- The program's name, version and description - used in the parser's configuration output (`std::cout << parser`).
 - Verbosity mode - `false` by default; if set to `true` the parser's configuration output will include more detailed info about arguments' parameters in addition to their names and help messages.
 - [Arguments](#adding-arguments) - specify the values/options accepted by the program.
 
 ```cpp
 ap::argument_parser parser;
 parser.program_name("Name of the program")
+      .program_version("alhpa")
       .program_description("Description of the program")
       .verbose();
 ```
 
+> [!TIP]
+>
+> You can specify the program version using a string (like in the example above) or using the `ap::version` structure:
+>
+> ```cpp
+> parser.program_version({0u, 0u, 0u})
+> parser.program_version({ .major = 1u, .minor = 1u, .patch = 1u });
+> ap::version ver{2u, 2u, 2u};
+> parser.program_version(ver);
+> ```
+>
+> **NOTE:** The `ap::version` struct
+> - contains the three members - `major`, `minor`, `patch` - all of which are of type `std::uint32_t`,
+> - defines a `std::string str() const` method which returns a `v{major}.{minor}.{path}` version string,
+> - defines the `std::ostream& operator<<` for stream insertion.
+
 <br/>
 <br/>
 <br/>
@@ -803,41 +822,37 @@ int main(int argc, char* argv[]) {
 
   ```shell
   ./power 2
-  # out:
-  # no exponent values given
+  no exponent values given
   ```
 
   ```shell
   ./power
-  # out:
-  # [ERROR] : No values parsed for a required argument [base]
-  # Program: power calculator
-  #
-  #   Calculates the value of an expression: base ^ exponent
-  #
-  # Positional arguments:
-  #
-  #   base : the exponentation base value
-  #
-  # Optional arguments:
-  #
-  #   --exponent, -e : the exponent value
-  #   --help, -h     : Display the help message
+  [ERROR] : No values parsed for a required argument [base]
+  Program: power calculator
+
+    Calculates the value of an expression: base ^ exponent
+
+  Positional arguments:
+
+    base : the exponentation base value
+
+  Optional arguments:
+
+    --exponent, -e : the exponent value
+    --help, -h     : Display the help message
   ```
 
 > [!IMPORTANT]
 >
 > For each positional argument there must be **exactly one value**.
 
-- Optional arguments are parsed only with a flag:
+- Optional arguments are parsed only with a flag. The values passed after an argument flag will be treated as the values of the last optional argument that preceeds them. If no argument flag preceeds a value argument, then it will be treated as an **unknown** value.
 
   ```shell
-  ./power 2 --exponent 1 2 3
-  # equivalent to: ./power 2 -e 1 2 3
-  # out:
-  # 2 ^ 1 = 2
-  # 2 ^ 2 = 4
-  # 2 ^ 3 = 8
+  ./power 2 --exponent 1 2 3 # equivalent to: ./power 2 -e 1 2 3
+  2 ^ 1 = 2
+  2 ^ 2 = 4
+  2 ^ 3 = 8
   ```
 
   You can use the flag for each command-line value:
@@ -850,25 +865,85 @@ int main(int argc, char* argv[]) {
 
   ```shell
   ./power 2 1 2 3
-  # out:
-  # [ERROR] : Failed to deduce the argument for values [1, 2, 3]
-  # Program: power calculator
-  #
-  #   Calculates the value of an expression: base ^ exponent
-  #
-  # Positional arguments:
-  #
-  #   base : the exponentation base value
-  #
-  # Optional arguments:
-  #
-  #   --exponent, -e : the exponent value
-  #   --help, -h     : Display the help message
+  [ERROR] : Failed to deduce the argument for values [1, 2, 3]
+  Program: power calculator
+
+    Calculates the value of an expression: base ^ exponent
+
+  Positional arguments:
+
+    base : the exponentation base value
+
+  Optional arguments:
+
+    --exponent, -e : the exponent value
+    --help, -h     : Display the help message
   ```
 
+> [!WARNING]
+>
+> If an optional argument has the `nargs` parameter set with an upper bound, then the values that succeed this argument's flag will be assigned to this argument only until the specified upper bound is reached. Further values will be treated as **unknown** values.
+>
+> **Example:**
+>
+> ```cpp
+> parser.add_optional_argument<int>("exponent", "e").nargs(ap::nargs::up_to(3))
+> ```
+> ```shell
+> ./power 2 -e 1 2 3 4 5
+> [ERROR] : Failed to deduce the argument for values [4, 5]
+> Program: power calculator
+>
+>   Calculates the value of an expression: base ^ exponent
+>
+> Positional arguments:
+>
+>   base : the exponentation base value
+>
+> Optional arguments:
+>
+>   --exponent, -e : the exponent value
+>   --help, -h     : Display the help message
+> ```
+
+<br />
+
+### Compound Arguments:
+
+Compound argument flags are **secondary** argument flags of which **every** character matches the secondary name of an optional argument.
+
+Example:
+
+```cpp
+parser.add_optional_argument("verbose", "v")
+      .nargs(0)
+      .help("Increase verbosity level");
+
+parser.add_flag("option", "o")
+      .help("Enable an option flag");
+
+parser.add_optional_argument<int>("numbers", "n")
+      .help("Provide integer values");
+
+parser.try_parse_args(argc, argv);
+
+std::cout << "Verbosity level: " << parser.count("verbose")
+          << "\nOption used: " << std::boolalpha << parser.value<bool>("use-option")
+          << "\nNumbers: " << join(parser.values<int>("numbers"), ", ") // join is an imaginary function :)
+          << std::endl;
+
+/*
+> ./program -vvon 1 2 3
+Verbosity level: 2
+Option used: true
+Numbers: 1, 2, 3
+```
+
 > [!IMPORTANT]
 >
-> The parser's behavior depends on the argument definitions - see [Argument Parameters](#argument-parameters) section.
+> - If there exists an argument whose secondary name matches a possible compound of other arguments, the parser will still treat the flag as a flag of the **single matching argument**, not as multiple flags.
+> - The argument parser will try to assign the values following a compound argument flag to the argument represented by the **last character** of the compound flag.
+
 
 <br/>
 <br/>