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.
2025-01-30 05:39:12 +02:00 · 2019-05-28 12:18:05 -04:00 · 2019-05-28 12:18:05 -04:00 · 404284b90f
commit 404284b90f
parent 20e5b92f36
10 changed files with 124 additions and 20 deletions
--- 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" .
--- 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}))
    {
--- 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;
        }
--- 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>
--- 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
--- 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)
--- 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?
 ***********************************************************************************************************************************/
--- 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);
--- a/src/config/define.auto.c
+++ b/src/config/define.auto.c
@ -123,6 +123,12 @@ static ConfigDefineCommandData configDefineCommandData[] = CFGDEFDATA_COMMAND_LI
    CFGDEFDATA_COMMAND
    (
        CFGDEFDATA_COMMAND_NAME("ls")
+
+        CFGDEFDATA_COMMAND_HELP_SUMMARY("List paths/files in the repository.")
+        CFGDEFDATA_COMMAND_HELP_DESCRIPTION
+        (
+            "This is intended to be a general purpose list function, but for now it only works on the repository."
+        )
    )

    CFGDEFDATA_COMMAND
@ -1127,6 +1133,20 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST
        (
            CFGDEFDATA_OPTION_COMMAND(cfgDefCmdLs)
        )
+
+        CFGDEFDATA_OPTION_OPTIONAL_LIST
+        (
+            CFGDEFDATA_OPTION_OPTIONAL_COMMAND_OVERRRIDE
+            (
+                CFGDEFDATA_OPTION_OPTIONAL_COMMAND(cfgDefCmdLs)
+
+                CFGDEFDATA_OPTION_OPTIONAL_HELP_SUMMARY("Filter output with a regular expression.")
+                CFGDEFDATA_OPTION_OPTIONAL_HELP_DESCRIPTION
+                (
+                    "The filter is applied against the file/path names before they are output."
+                )
+            )
+        )
    )

    // -----------------------------------------------------------------------------------------------------------------------------
@ -4009,6 +4029,20 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST
            )

            CFGDEFDATA_OPTION_OPTIONAL_DEFAULT("asc")
+
+            CFGDEFDATA_OPTION_OPTIONAL_COMMAND_OVERRRIDE
+            (
+                CFGDEFDATA_OPTION_OPTIONAL_COMMAND(cfgDefCmdLs)
+
+                CFGDEFDATA_OPTION_OPTIONAL_HELP_SUMMARY("Sort output ascending/descending.")
+                CFGDEFDATA_OPTION_OPTIONAL_HELP_DESCRIPTION
+                (
+                    "The following sort types are supported:\n"
+                    "\n"
+                    "* asc - sort ascending.\n"
+                    "* desc - sort descending."
+                )
+            )
        )
    )

--- a/test/src/module/config/configTest.c
+++ b/test/src/module/config/configTest.c
@ -60,6 +60,8 @@ testRun(void)

        // -------------------------------------------------------------------------------------------------------------------------
        TEST_RESULT_VOID(cfgCommandSet(cfgCmdBackup), "command set to backup");
+        TEST_RESULT_INT(cfgCommandInternal(cfgCmdLocal), true, "local is internal");
+        TEST_RESULT_INT(cfgCommandInternal(cfgCmdBackup), false, "backup is external");
        TEST_RESULT_INT(cfgLogLevelDefault(), logLevelInfo, "default log level is info");
        TEST_RESULT_BOOL(cfgLogFile(), true, "log file is on");
        TEST_RESULT_BOOL(cfgLockRequired(), true, "lock is required");