feat: add a silent option to subcommands (#529)

Co-authored-by: Henry Schreiner <HenrySchreinerIII@gmail.com>

README.md

@@ -560,6 +560,7 @@ There are several options that are supported on the main app and subcommands and
 -   `.disable()`: Specify that the subcommand is disabled, if given with a bool value it will enable or disable the subcommand or option group.
 -   `.disabled_by_default()`: Specify that at the start of parsing the subcommand/option_group should be disabled. This is useful for allowing some Subcommands to trigger others.
 -   `.enabled_by_default()`: Specify that at the start of each parse the subcommand/option_group should be enabled.  This is useful for allowing some Subcommands to disable others.
+-   `.silent()`: 🚧 Specify that the subcommand is silent meaning that if used it won't show up in the subcommand list.  This allows the use of subcommands as modifiers
 -   `.validate_positionals()`: Specify that positionals should pass validation before matching.  Validation is specified through `transform`, `check`, and `each` for an option.  If an argument fails validation it is not an error and matching proceeds to the next available positional or extra arguments.
 -   `.excludes(option_or_subcommand)`: If given an option pointer or pointer to another subcommand, these subcommands cannot be given together.  In the case of options, if the option is passed the subcommand cannot be used and will generate an error.
 -   `.needs(option_or_subcommand)`: 🆕 If given an option pointer or pointer to another subcommand, the subcommands will require the given option to have been given before this subcommand is validated which occurs prior to execution of any callback or after parsing is completed.

book/chapters/subcommands.md

@@ -112,3 +112,18 @@ Here, `--shared_flag` was set on the main app, and on the command line it "falls
 
 This is a special mode that allows "prefix" commands, where the parsing completely stops when it gets to an unknown option. Further unknown options are ignored, even if they could match. Git is the traditional example for prefix commands; if you run git with an unknown subcommand, like "`git thing`", it then calls another command called "`git-thing`" with the remaining options intact.
 
+### Silent subcommands
+
+Subcommands can be modified by using the `silent` option.  This will prevent the subcommand from showing up in the get_subcommands list.  This can be used to make subcommands into modifiers. For example, a help subcommand might look like
+
+```c++
+    auto sub1 = app.add_subcommand("help")->silent();
+    sub1->parse_complete_callback([]() { throw CLI::CallForHelp(); });
+```
+
+This would allow calling help such as:
+
+```bash
+./app help
+./app help sub1
+```

include/CLI/App.hpp

@@ -218,11 +218,12 @@ class App {
     /// If set to true positional options are validated before assigning INHERITABLE
     bool validate_positionals_{false};
 
-    /// A pointer to the parent if this is a subcommand
-    App *parent_{nullptr};
+    /// indicator that the subcommand is silent and won't show up in subcommands list
+    /// This is potentially useful as a modifier subcommand
+    bool silent_{false};
 
     /// Counts the number of times this command/subcommand was parsed
-    std::size_t parsed_{0};
+    std::uint32_t parsed_{0U};
 
     /// Minimum required subcommands (not inheritable!)
     std::size_t require_subcommand_min_{0};
@@ -236,6 +237,9 @@ class App {
     /// Max number of options allowed. 0 is unlimited (not inheritable)
     std::size_t require_option_max_{0};
 
+    /// A pointer to the parent if this is a subcommand
+    App *parent_{nullptr};
+
     /// The group membership INHERITABLE
     std::string group_{"Subcommands"};
 
@@ -396,6 +400,12 @@ class App {
         return this;
     }
 
+    /// silence the subcommand from showing up in the processed list
+    App *silent(bool silence = true) {
+        silent_ = silence;
+        return this;
+    }
+
     /// Set the subcommand to be disabled by default, so on clear(), at the start of each parse it is disabled
     App *disabled_by_default(bool disable = true) {
         if(disable) {
@@ -1767,6 +1777,9 @@ class App {
     /// Get the status of disabled
     bool get_disabled() const { return disabled_; }
 
+    /// Get the status of silence
+    bool get_silent() const { return silent_; }
+
     /// Get the status of disabled
     bool get_immediate_callback() const { return immediate_callback_; }
 
@@ -2673,12 +2686,16 @@ class App {
         auto com = _find_subcommand(args.back(), true, true);
         if(com != nullptr) {
             args.pop_back();
-            parsed_subcommands_.push_back(com);
+            if(!com->silent_) {
+                parsed_subcommands_.push_back(com);
+            }
             com->_parse(args);
             auto parent_app = com->parent_;
             while(parent_app != this) {
                 parent_app->_trigger_pre_parse(args.size());
-                parent_app->parsed_subcommands_.push_back(com);
+                if(!com->silent_) {
+                    parent_app->parsed_subcommands_.push_back(com);
+                }
                 parent_app = parent_app->parent_;
             }
             return true;

tests/SubcommandTest.cpp

@@ -1466,6 +1466,21 @@ TEST_F(ManySubcommands, SubcommandTriggeredOn) {
     EXPECT_THROW(run(), CLI::ExtrasError);
 }
 
+TEST_F(ManySubcommands, SubcommandSilence) {
+
+    sub1->silent();
+    args = {"sub1", "sub2"};
+    EXPECT_NO_THROW(run());
+
+    auto subs = app.get_subcommands();
+    EXPECT_EQ(subs.size(), 1U);
+    sub1->silent(false);
+    EXPECT_FALSE(sub1->get_silent());
+    run();
+    subs = app.get_subcommands();
+    EXPECT_EQ(subs.size(), 2U);
+}
+
 TEST_F(TApp, UnnamedSub) {
     double val{0.0};
     auto sub = app.add_subcommand("", "empty name");
@@ -1622,6 +1637,23 @@ TEST_F(TApp, OptionGroupAlias) {
     EXPECT_EQ(val, -3);
 }
 
+TEST_F(TApp, subcommand_help) {
+    auto sub1 = app.add_subcommand("help")->silent();
+    bool flag{false};
+    app.add_flag("--one", flag, "FLAGGER");
+    sub1->parse_complete_callback([]() { throw CLI::CallForHelp(); });
+    bool called{false};
+    args = {"help"};
+    try {
+        run();
+    } catch(const CLI::CallForHelp &) {
+        called = true;
+    }
+    auto helpstr = app.help();
+    EXPECT_THAT(helpstr, HasSubstr("FLAGGER"));
+    EXPECT_TRUE(called);
+}
+
 TEST_F(TApp, AliasErrors) {
     auto sub1 = app.add_subcommand("sub1");
     auto sub2 = app.add_subcommand("sub2");