Add internal flag for commands.

Allow commands to be skipped by default in the command help but still work if help is requested for the command directly. There may be other uses for the flag in the future. Update help for ls now that it is exposed.
pgbackrest · May 28, 2019 · 404284b · 404284b
1 parent 20e5b92
commit 404284b
Show file tree

Hide file tree

Showing 10 changed files with 124 additions and 20 deletions.
diff --git a/build/lib/pgBackRestBuild/Config/Build.pm b/build/lib/pgBackRestBuild/Config/Build.pm
@@ -160,6 +160,7 @@ sub buildConfig
             "    (\n" .
             "        CONFIG_COMMAND_NAME(${strCommandConst})\n" .
             "\n" .
+            "        CONFIG_COMMAND_INTERNAL(" . ($rhCommand->{&CFGDEF_INTERNAL} ? 'true' : 'false') . ")\n" .
             "        CONFIG_COMMAND_LOG_FILE(" . ($rhCommand->{&CFGDEF_LOG_FILE} ? 'true' : 'false') . ")\n" .
             "        CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevel" . ucfirst(lc($rhCommand->{&CFGDEF_LOG_LEVEL_DEFAULT})) . ")\n" .
             "        CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevel" .

diff --git a/build/lib/pgBackRestBuild/Config/Data.pm b/build/lib/pgBackRestBuild/Config/Data.pm
@@ -596,6 +596,7 @@ my $rhCommandDefine =
 
     &CFGCMD_ARCHIVE_GET_ASYNC =>
     {
+        &CFGDEF_INTERNAL => true,
         &CFGDEF_LOG_FILE => true,
         &CFGDEF_LOCK_REQUIRED => true,
         &CFGDEF_LOCK_TYPE => CFGDEF_LOCK_TYPE_ARCHIVE,
@@ -612,6 +613,7 @@ my $rhCommandDefine =
 
     &CFGCMD_ARCHIVE_PUSH_ASYNC =>
     {
+        &CFGDEF_INTERNAL => true,
         &CFGDEF_LOG_FILE => true,
         &CFGDEF_LOCK_REQUIRED => true,
         &CFGDEF_LOCK_REMOTE_REQUIRED => true,
@@ -652,11 +654,13 @@ my $rhCommandDefine =
 
     &CFGCMD_LOCAL =>
     {
+        &CFGDEF_INTERNAL => true,
         &CFGDEF_LOG_LEVEL_STDERR_MAX => ERROR,
     },
 
     &CFGCMD_REMOTE =>
     {
+        &CFGDEF_INTERNAL => true,
         &CFGDEF_LOG_LEVEL_STDERR_MAX => ERROR,
     },
 
@@ -692,6 +696,7 @@ my $rhCommandDefine =
 
     &CFGCMD_STORAGE_LIST =>
     {
+        &CFGDEF_INTERNAL => true,
         &CFGDEF_LOG_FILE => false,
         &CFGDEF_LOG_LEVEL_DEFAULT => DEBUG,
         &CFGDEF_PARAMETER_ALLOWED => true,
@@ -2575,6 +2580,12 @@ my %hConfigDefine =
 ####################################################################################################################################
 foreach my $strCommand (sort(keys(%{$rhCommandDefine})))
 {
+    # Commands are external by default
+    if (!defined($rhCommandDefine->{$strCommand}{&CFGDEF_INTERNAL}))
+    {
+        $rhCommandDefine->{$strCommand}{&CFGDEF_INTERNAL} = false;
+    }
+
     # Log files are created by default
     if (!defined($rhCommandDefine->{$strCommand}{&CFGDEF_LOG_FILE}))
     {

diff --git a/doc/lib/BackRestDoc/Common/DocConfig.pm b/doc/lib/BackRestDoc/Common/DocConfig.pm
@@ -196,7 +196,7 @@ sub process
     foreach my $strCommand (cfgDefineCommandList())
     {
         if ($strCommand eq CFGCMD_REMOTE || $strCommand eq CFGCMD_LOCAL || $strCommand eq CFGCMD_ARCHIVE_GET_ASYNC ||
-            $strCommand eq CFGCMD_ARCHIVE_PUSH_ASYNC || $strCommand eq CFGCMD_STORAGE_LIST)
+            $strCommand eq CFGCMD_ARCHIVE_PUSH_ASYNC)
         {
             next;
         }

diff --git a/doc/xml/reference.xml b/doc/xml/reference.xml
@@ -1218,16 +1218,40 @@
                 </command-example-list>
             </command>
 
-            <!-- OPERATION - STORAGE-LIST COMMAND -->
-            <command id="storage-list" name="Storage List">
+            <!-- OPERATION - LS COMMAND -->
+            <command id="ls" name="Storage List">
                 <summary>List paths/files in the repository.</summary>
 
                 <text>This is intended to be a general purpose list function, but for now it only works on the repository.</text>
 
+                <option-list>
+                    <!-- OPERATION - LS COMMAND - FILTER OPTION -->
+                    <option id="filter" name="Filter Output">
+                        <summary>Filter output with a regular expression.</summary>
+
+                        <text>The filter is applied against the file/path names before they are output.</text>
+
+                        <example>(F|D|I)$</example>
+                    </option>
+
+                    <!-- OPERATION - LS COMMAND - SORT OPTION -->
+                    <option id="sort" name="Sort Output">
+                        <summary>Sort output ascending/descending.</summary>
+
+                        <text>The following sort types are supported:
+                        <ul>
+                            <li><id>asc</id> - sort ascending.</li>
+                            <li><id>desc</id> - sort descending.</li>
+                        </ul></text>
+
+                        <example>desc</example>
+                    </option>
+                </option-list>
+
                 <command-example-list>
                     <command-example title="List all backups in a stanza">
                         <text><code-block title="">
-                            {[backrest-exe]} storage-list backup/demo
+                            {[backrest-exe]} ls backup/demo
                         </code-block>
 
                         List all backups in the demo stanza.</text>

diff --git a/src/command/help/help.c b/src/command/help/help.c
@@ -165,32 +165,26 @@ helpRender(void)
 
             for (ConfigCommand commandId = 0; commandId < CFG_COMMAND_TOTAL; commandId++)
             {
-                if (commandId == cfgCmdNone)
+                if (commandId == cfgCmdNone || cfgCommandInternal(commandId))
                     continue;
 
-                // Only check size if the command has a help summary so we know it is a documented command
-                if (cfgDefCommandHelpSummary(cfgCommandDefIdFromId(commandId)) != NULL &&
-                    strlen(cfgCommandName(commandId)) > commandSizeMax)
-                {
+                if (strlen(cfgCommandName(commandId)) > commandSizeMax)
                     commandSizeMax = strlen(cfgCommandName(commandId));
-                }
             }
 
             // Output help for each command
             for (ConfigCommand commandId = 0; commandId < CFG_COMMAND_TOTAL; commandId++)
             {
-                if (commandId == cfgCmdNone)
+                if (commandId == cfgCmdNone || cfgCommandInternal(commandId))
                     continue;
 
-                const char *helpSummary = cfgDefCommandHelpSummary(cfgCommandDefIdFromId(commandId));
-
-                if (helpSummary != NULL)
-                {
-                    strCatFmt(
-                        result, "    %s%*s%s\n", cfgCommandName(commandId),
-                        (int)(commandSizeMax - strlen(cfgCommandName(commandId)) + 2), "",
-                        strPtr(helpRenderText(STR(helpSummary), commandSizeMax + 6, false, CONSOLE_WIDTH)));
-                }
+                strCatFmt(
+                    result, "    %s%*s%s\n", cfgCommandName(commandId),
+                    (int)(commandSizeMax - strlen(cfgCommandName(commandId)) + 2), "",
+                    strPtr(
+                        helpRenderText(
+                            STR(cfgDefCommandHelpSummary(cfgCommandDefIdFromId(commandId))), commandSizeMax + 6, false,
+                            CONSOLE_WIDTH)));
             }
 
             // Construct message for more help

diff --git a/src/config/config.auto.c b/src/config/config.auto.c
@@ -36,6 +36,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_ARCHIVE_GET)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(false)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -49,6 +50,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_ARCHIVE_GET_ASYNC)
 
+        CONFIG_COMMAND_INTERNAL(true)
         CONFIG_COMMAND_LOG_FILE(true)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -62,6 +64,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_ARCHIVE_PUSH)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(false)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -75,6 +78,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_ARCHIVE_PUSH_ASYNC)
 
+        CONFIG_COMMAND_INTERNAL(true)
         CONFIG_COMMAND_LOG_FILE(true)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -88,6 +92,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_BACKUP)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(true)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -101,6 +106,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_CHECK)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(false)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -114,6 +120,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_EXPIRE)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(true)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -127,6 +134,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_HELP)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(false)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelDebug)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -140,6 +148,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_INFO)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(false)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelDebug)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -153,6 +162,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_LOCAL)
 
+        CONFIG_COMMAND_INTERNAL(true)
         CONFIG_COMMAND_LOG_FILE(true)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelError)
@@ -166,6 +176,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_LS)
 
+        CONFIG_COMMAND_INTERNAL(true)
         CONFIG_COMMAND_LOG_FILE(false)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelDebug)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -179,6 +190,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_REMOTE)
 
+        CONFIG_COMMAND_INTERNAL(true)
         CONFIG_COMMAND_LOG_FILE(true)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelError)
@@ -192,6 +204,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_RESTORE)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(true)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -205,6 +218,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_STANZA_CREATE)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(true)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -218,6 +232,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_STANZA_DELETE)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(true)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -231,6 +246,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_STANZA_UPGRADE)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(true)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -244,6 +260,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_START)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(true)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -257,6 +274,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_STOP)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(true)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelInfo)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)
@@ -270,6 +288,7 @@ static ConfigCommandData configCommandData[CFG_COMMAND_TOTAL] = CONFIG_COMMAND_L
     (
         CONFIG_COMMAND_NAME(CFGCMD_VERSION)
 
+        CONFIG_COMMAND_INTERNAL(false)
         CONFIG_COMMAND_LOG_FILE(false)
         CONFIG_COMMAND_LOG_LEVEL_DEFAULT(logLevelDebug)
         CONFIG_COMMAND_LOG_LEVEL_STDERR_MAX(logLevelTrace)

diff --git a/src/config/config.c b/src/config/config.c
@@ -17,6 +17,7 @@ typedef struct ConfigCommandData
 {
     const char *name;
 
+    bool internal:1;
     bool lockRequired:1;
     bool lockRemoteRequired:1;
     unsigned int lockType:2;
@@ -34,6 +35,8 @@ typedef struct ConfigCommandData
 #define CONFIG_COMMAND(...)                                                                                                        \
     {__VA_ARGS__},
 
+#define CONFIG_COMMAND_INTERNAL(internalParam)                                                                                     \
+    .internal = internalParam,
 #define CONFIG_COMMAND_LOCK_REQUIRED(lockRequiredParam)                                                                            \
     .lockRequired = lockRequiredParam,
 #define CONFIG_COMMAND_LOCK_REMOTE_REQUIRED(lockRemoteRequiredParam)                                                               \
@@ -328,6 +331,21 @@ cfgExeSet(const String *exeParam)
     FUNCTION_TEST_RETURN_VOID();
 }
 
+/***********************************************************************************************************************************
+Is this command internal-only?
+***********************************************************************************************************************************/
+bool
+cfgCommandInternal(ConfigCommand commandId)
+{
+    FUNCTION_TEST_BEGIN();
+        FUNCTION_TEST_PARAM(ENUM, commandId);
+    FUNCTION_TEST_END();
+
+    ASSERT(commandId < cfgCmdNone);
+
+    FUNCTION_TEST_RETURN(configCommandData[commandId].internal);
+}
+
 /***********************************************************************************************************************************
 Does this command require an immediate lock?
 ***********************************************************************************************************************************/

diff --git a/src/config/config.h b/src/config/config.h
@@ -29,6 +29,7 @@ Command Functions
 Access the current command and command parameters.
 ***********************************************************************************************************************************/
 ConfigCommand cfgCommand(void);
+bool cfgCommandInternal(ConfigCommand commandId);
 const char *cfgCommandName(ConfigCommand commandId);
 
 bool cfgLockRequired(void);