YT-CPPAP-65: Argument groupt hiding

.clangd

@@ -0,0 +1,23 @@
+CompileFlags:
+  Add:
+    - -std=c++23
+    - -xc++-header
+    - -Iinclude
+    - -Itests/include
+    - -Itests/external
+    - -Wall
+    - -Wextra
+    - -ftemplate-depth=512
+
+Diagnostics:
+  UnusedIncludes: None
+  ClangTidy:
+    Add:
+      - bugprone-*
+      - modernize-*
+      - performance-*
+    Remove:
+      - modernize-use-trailing-return-type
+
+Index:
+  Background: Build

.github/workflows/clang.yaml

@@ -2,7 +2,7 @@ name: Clang
 on:
   push:
     branches:
-      - '*'
+      - "*"
     paths:
       - .github/workflows/clang.yaml
       - include/**
@@ -23,17 +23,17 @@ jobs:
 
       - name: Prepare
         env:
-          CC:  clang-17
+          CC: clang-17
           CXX: clang++-17
         run: |
           cmake -B build_clang -DBUILD_TESTS=ON -DCMAKE_CXX_COMPILER=$CXX -DCMAKE_C_COMPILER=$CC
         continue-on-error: false
 
-      - name: Build tests
+      - name: Build and Run tests
         run: |
-          cmake --build build_clang/ -j 4
+          cmake --build build_clang/ -j4
         continue-on-error: false
 
       - name: Run tests
         run: |
-          ctest --test-dir build_clang/tests/ -V
+          ./build_clang/tests/run_uts

.github/workflows/demo.yaml

@@ -2,7 +2,7 @@ name: demo
 on:
   push:
     branches:
-      - '*'
+      - "*"
     paths:
       - .github/workflows/demo.yaml
       - .gitmodules

.github/workflows/documentation.yaml

@@ -3,10 +3,10 @@ name: documentation
 on:
   pull_request:
     branches:
-      - '*'
+      - "*"
   push:
     tags:
-      - 'v*'
+      - "v*"
 
 jobs:
   build-doc:

.github/workflows/format.yaml

@@ -2,7 +2,7 @@ name: format
 on:
   push:
     branches:
-      - '*'
+      - "*"
     paths:
       - .github/workflows/format.yaml
       - scripts/format.py
@@ -31,4 +31,4 @@ jobs:
       - name: Test formatting
         shell: bash
         run: |
-          python3 scripts/format.py --check
+          python3 scripts/format.py --check -exe clang-format-18

.github/workflows/gcc.yaml

@@ -2,7 +2,7 @@ name: GCC
 on:
   push:
     branches:
-      - '*'
+      - "*"
     paths:
       - .github/workflows/gcc.yaml
       - include/**
@@ -23,7 +23,7 @@ jobs:
 
       - name: Prepare
         env:
-          CC:  gcc-13
+          CC: gcc-13
           CXX: g++-13
         run: |
           cmake -B build_gcc -DBUILD_TESTS=ON -DCMAKE_CXX_COMPILER=$CXX -DCMAKE_C_COMPILER=$CC
@@ -36,4 +36,4 @@ jobs:
 
       - name: Run tests
         run: |
-          ctest --test-dir build_gcc/tests/ -V
+          ./build_gcc/tests/run_uts

.github/workflows/license.yaml

@@ -2,7 +2,7 @@ name: license
 on:
   push:
     branches:
-      - '*'
+      - "*"
     paths:
       - .github/workflows/license.yaml
       - scripts/check_licence.py

.github/workflows/msvc.yaml

@@ -2,7 +2,7 @@ name: MSVC
 on:
   push:
     branches:
-      - '*'
+      - "*"
     paths:
       - .github/workflows/msvc.yaml
       - include/**
@@ -33,5 +33,5 @@ jobs:
 
       - name: Run tests
         run: |
-          ctest --test-dir build_msvc/tests -V -C Debug
+          ./build_msvc/tests/Debug/run_uts.exe
         shell: powershell

CMakeLists.txt

@@ -7,7 +7,7 @@ else()
 endif()
 
 project(cpp-ap
-    VERSION 3.0.1
+    VERSION 3.1.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         = 3.0.1
+PROJECT_NUMBER         = 3.1.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 = "3.0.1",
+    version = "3.1.0",
 )

docs/dev_notes.md

@@ -2,34 +2,34 @@
 
 <br />
 
-## Building and testing
+## Building and Testing
 
 > [!NOTE]
 >
 > The project uses [doctest](https://github.com/doctest/doctest) framework for unit testing, however it is already installed in the [tests/external](/tests/external/) directory, so there is no need to install it sepparately.
 
-### Build the testing executable
+### Build the Testing Executable
 
 ```shell
 cmake -B build -DBUILD_TESTS=ON
-cmake --build build/ # -j <njobs>
+cmake --build build/ # -j<njobs>
 ```
 
-This will build each test file as a separate executable in the `build/tests/` directory.
+This will build a `run_uts` executable executable in the `build/tests/` directory.
 
-### Run the tests
+### Runing the Tests
 
-You can run tests from each test file separately with:
+To run the project's unit tests, simply run the testing executable:
 
 ```shell
-./build/tests/<test-name>
+./build/tests/run_uts
 ```
 
-To execute all tests at once run:
-
-```shell
-ctest --test-dir build/tests/ # -V (to capture output from each test executable)
-```
+> [!TIP]
+> Each test file defines its unique test suite with the same name as the test file. To run tests within such test suite, execute:
+> ```shell
+> ./build/tests/run_uts -ts=<test-suite-name>
+> ```
 
 <br />
 <br />

docs/tutorial.md

@@ -908,6 +908,15 @@ auto& out_opts = parser.add_group("Output Options")
 >
 > Consider the example in the section below. Normally the `--output, -o` argument would expect a value to be given in the command-line. However, if the `--print, -p` flag is used, then the `nargs` requirement of the `--output, -o` argument will not be verified, and therefore no exception will be thrown, even though the `nargs` requirement is not satisfied.
 
+Additionally, argument groups can be marked `hidden` - a hidden group will not be visible in the parser's help output (even if it has visible arguments).
+
+```cpp
+auto& hidden_opts = parser.add_group("Hidden Options").hidden();
+parser.add_optional_argument("visible").help("A visible arg");
+```
+
+In the example above, neither the `Hidden Options` group nor the `visible` arg will be visible in the parser's help output.
+
 ### Complete Example
 
 Below is a small program that demonstrates how to use a mutually exclusive group of required arguments:

include/ap/action/predefined.hpp

@@ -6,8 +6,8 @@
 
 #pragma once
 
+#include "ap/action/util/helpers.hpp"
 #include "ap/exceptions.hpp"
-#include "util/helpers.hpp"
 
 #include <filesystem>
 #include <ostream>

include/ap/action/util/helpers.hpp

@@ -9,7 +9,7 @@
 
 #pragma once
 
-#include "concepts.hpp"
+#include "ap/action/util/concepts.hpp"
 
 #include <utility>
 #include <variant>

include/ap/argument.hpp

@@ -6,14 +6,14 @@
 
 #pragma once
 
-#include "action/predefined.hpp"
-#include "action/util/helpers.hpp"
-#include "detail/argument_base.hpp"
-#include "detail/help_builder.hpp"
-#include "nargs/range.hpp"
-#include "types.hpp"
-#include "util/concepts.hpp"
-#include "util/ranges.hpp"
+#include "ap/action/predefined.hpp"
+#include "ap/action/util/helpers.hpp"
+#include "ap/detail/argument_base.hpp"
+#include "ap/detail/help_builder.hpp"
+#include "ap/nargs/range.hpp"
+#include "ap/types.hpp"
+#include "ap/util/concepts.hpp"
+#include "ap/util/ranges.hpp"
 
 #ifdef AP_TESTING
 

include/ap/argument_group.hpp

@@ -6,7 +6,7 @@
 
 #pragma once
 
-#include "detail/argument_base.hpp"
+#include "ap/detail/argument_base.hpp"
 
 #include <memory>
 
@@ -42,6 +42,20 @@ class argument_group {
 public:
     argument_group() = delete;
 
+    /**
+     * @brief Set the `hidden` attribute of the group.
+     *
+     * - If set to true, the group will be hidden from the help output.
+     * - Groups are NOT hidden by default.
+     *
+     * @param h The value to set for the attribute (default: true).
+     * @return Reference to the group instance.
+     */
+    argument_group& hidden(const bool h = true) noexcept {
+        this->_hidden = h;
+        return *this;
+    }
+
     /**
      * @brief Set the `required` attribute of the group.
      *
@@ -100,6 +114,7 @@ class argument_group {
     std::string _name; ///< Name of the group (used in help output).
     arg_ptr_vec_t _arguments; ///< A list of arguments that belong to this group.
 
+    bool _hidden : 1 = false; ///< The hidden attribute value (default: false).
     bool _required : 1 = false; ///< The required attribute value (default: false).
     bool _mutually_exclusive : 1 =
         false; ///< The mutually exclusive attribute value (default: false).

include/ap/argument_parser.hpp

@@ -9,10 +9,10 @@
 
 #pragma once
 
-#include "argument.hpp"
-#include "argument_group.hpp"
-#include "detail/argument_token.hpp"
-#include "types.hpp"
+#include "ap/argument.hpp"
+#include "ap/argument_group.hpp"
+#include "ap/detail/argument_token.hpp"
+#include "ap/types.hpp"
 
 #include <algorithm>
 #include <format>
@@ -1508,23 +1508,25 @@ class argument_parser {
      */
     void _print_group(std::ostream& os, const argument_group& group, const bool verbose)
         const noexcept {
+        if (group._hidden)
+            return;
+
         auto visible_args = std::views::filter(group._arguments, [](const auto& arg) {
             return not arg->is_hidden();
         });
 
         if (std::ranges::empty(visible_args))
             return;
 
-        os << '\n' << group._name << ":";
+        os << '\n' << group._name << ':';
 
-        std::vector<std::string> group_attrs;
+        std::vector<std::string_view> group_attrs;
         if (group._required)
             group_attrs.emplace_back("required");
         if (group._mutually_exclusive)
             group_attrs.emplace_back("mutually exclusive");
         if (not group_attrs.empty())
             os << " (" << util::join(group_attrs) << ')';
-
         os << '\n';
 
         if (verbose) {

include/ap/detail/argument_base.hpp

@@ -9,8 +9,8 @@
 
 #pragma once
 
-#include "argument_name.hpp"
-#include "help_builder.hpp"
+#include "ap/detail/argument_name.hpp"
+#include "ap/detail/help_builder.hpp"
 
 #include <any>
 #include <iostream>

include/ap/detail/argument_token.hpp

@@ -6,9 +6,10 @@
 
 #pragma once
 
-#include "argument_base.hpp"
+#include "ap/detail/argument_base.hpp"
 
 #include <cstdint>
+#include <memory>
 #include <string>
 #include <vector>
 

include/ap/detail/help_builder.hpp

@@ -9,9 +9,9 @@
 
 #pragma once
 
+#include "ap/detail/argument_name.hpp"
 #include "ap/util/concepts.hpp"
 #include "ap/util/string.hpp"
-#include "argument_name.hpp"
 
 #include <cstdint>
 #include <format>

include/ap/util/ranges.hpp

@@ -9,7 +9,7 @@
 
 #pragma once
 
-#include "concepts.hpp"
+#include "ap/util/concepts.hpp"
 
 #include <any>
 #include <ranges>