add an example of capturing the arguments after a specific option. (#944)

Based on Issue #931 and #942.  
Add an example of how to do what those issues were requesting.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

README.md

@@ -52,7 +52,6 @@ set with a simple and intuitive interface.
     - [Formatting](#formatting)
     - [Subclassing](#subclassing)
     - [How it works](#how-it-works)
-      - [Example](#example-1)
     - [Unicode support](#unicode-support)
       - [Note on using Unicode paths](#note-on-using-unicode-paths)
     - [Utilities](#utilities)
@@ -1581,6 +1580,9 @@ GitBook][gitbook].
 Several short examples of different features are included in the repository. A
 brief description of each is included here
 
+- [arg_capture](https://github.com/CLIUtils/CLI11/blob/main/examples/arg_capture.cpp):
+  Example of capturing all remaining arguments after a specific option, using
+  subcommand and prefix_command() with an alias.
 - [callback_passthrough](https://github.com/CLIUtils/CLI11/blob/main/examples/callback_passthrough.cpp):
   Example of directly passing remaining arguments through to a callback function
   which generates a CLI11 application based on existing arguments.

examples/CMakeLists.txt

@@ -189,6 +189,12 @@ add_test(NAME prefix_command COMMAND prefix_command -v 3 2 1 -- other one two 3)
 set_property(TEST prefix_command PROPERTY PASS_REGULAR_EXPRESSION "Prefix: 3 : 2 : 1"
                                           "Remaining commands: other one two 3")
 
+add_cli_exe(arg_capture arg_capture.cpp)
+add_test(NAME arg_capture COMMAND arg_capture -v 27 --sub -v 13 --val prefix)
+set_property(TEST arg_capture PROPERTY PASS_REGULAR_EXPRESSION "value=27")
+add_test(NAME arg_capture2 COMMAND arg_capture -v 27 --sub -v 13 --val prefix)
+set_property(TEST arg_capture2 PROPERTY PASS_REGULAR_EXPRESSION "after Args:-v 13 --val prefix")
+
 add_cli_exe(callback_passthrough callback_passthrough.cpp)
 add_test(NAME callback_passthrough1 COMMAND callback_passthrough --argname t2 --t2 test)
 set_property(TEST callback_passthrough1 PROPERTY PASS_REGULAR_EXPRESSION "the value is now test")

examples/arg_capture.cpp

@@ -0,0 +1,34 @@
+// Copyright (c) 2017-2023, University of Cincinnati, developed by Henry Schreiner
+// under NSF AWARD 1414736 and by the respective contributors.
+// All rights reserved.
+//
+// SPDX-License-Identifier: BSD-3-Clause
+
+// Code modified from https://github.com/CLIUtils/CLI11/issues/559
+
+#include <CLI/CLI.hpp>
+#include <iostream>
+#include <string>
+
+/** This example demonstrates the use of `prefix_command` on a subcommand
+to capture all subsequent arguments along with an alias to make it appear as a regular options.
+
+All the values after the "sub" or "--sub" are available in the remaining() method.
+*/
+int main(int argc, const char *argv[]) {
+
+    int value{0};
+    CLI::App app{"Test App"};
+    app.add_option("-v", value, "value");
+
+    auto *subcom = app.add_subcommand("sub", "")->prefix_command();
+    subcom->alias("--sub");
+    CLI11_PARSE(app, argc, argv);
+
+    std::cout << "value=" << value << std::endl;
+    std::cout << "after Args:";
+    for(const auto &aarg : subcom->remaining()) {
+        std::cout << aarg << " ";
+    }
+    std::cout << std::endl;
+}

examples/testEXE.cpp

@@ -12,15 +12,17 @@
 
 int main(int argc, const char *argv[]) {
 
-    int logLevel{0};
+    int value{0};
     CLI::App app{"Test App"};
+    app.add_option("-v", value, "value");
 
-    app.add_option("-v", logLevel, "level");
-
-    auto *subcom = app.add_subcommand("sub", "")->fallthrough();
-    subcom->preparse_callback([&app](size_t) { app.get_subcommand("sub")->add_option_group("group"); });
-
+    auto *subcom = app.add_subcommand("sub", "")->prefix_command();
     CLI11_PARSE(app, argc, argv);
 
-    std::cout << "level: " << logLevel << std::endl;
+    std::cout << "value =" << value << std::endl;
+    std::cout << "after Args:";
+    for(const auto &aarg : subcom->remaining()) {
+        std::cout << aarg << " ";
+    }
+    std::cout << std::endl;
 }