Fixed issue #132: Improved command-line help.

Some platform specific fixes and added regression tests to detect issues.

bin/pg_backrest

@@ -89,7 +89,7 @@ eval
     # Display version
     if (commandTest(CMD_HELP) || commandTest(CMD_VERSION))
     {
-        syswrite(*STDOUT, (!$bConfigResult ? "\n" : '') .BACKREST_NAME . ' ' . BACKREST_VERSION);
+        syswrite(*STDOUT, (!$bConfigResult ? "\n" : '') . BACKREST_NAME . ' ' . BACKREST_VERSION);
 
         # If the command is version then exit
         if (commandTest(CMD_VERSION))
@@ -103,8 +103,8 @@ eval
     if (commandTest(CMD_HELP))
     {
         # Load module dynamically
-        require BackRest::Config::Config::ConfigHelp;
+        require BackRest::Config::ConfigHelp;
-        BackRest::Config::Config::ConfigHelp->import();
+        BackRest::Config::ConfigHelp->import();
 
         # Generate help and exit
         configHelp($ARGV[1], $ARGV[2]);

doc/html/default.css

@@ -108,13 +108,13 @@ Menu
 /*******************************************************************************
 Section
 *******************************************************************************/
-doc-install, doc-configure, doc-intro
+.section1
 {
 	display:block;
 	margin-top: 8px;
 }
 
-doc-install-header, doc-configure-header
+section1-header
 {
 	display:block;
 	background-color: #dddddd;

lib/BackRest/Config/ConfigHelp.pm

@@ -1,7 +1,7 @@
 ####################################################################################################################################
 # CONFIG HELP MODULE
 ####################################################################################################################################
-package BackRest::Config::Config::ConfigHelp;
+package BackRest::Config::ConfigHelp;
 
 use strict;
 use warnings FATAL => qw(all);
@@ -55,8 +55,8 @@ sub configHelp
     my $strOption = shift;
 
     # Load module dynamically
-    require BackRest::Config::Config::ConfigHelpData;
+    require BackRest::Config::ConfigHelpData;
-    BackRest::Config::Config::ConfigHelpData->import();
+    BackRest::Config::ConfigHelpData->import();
 
     # Get config data
     my $oCommandHash = commandHashGet();
@@ -234,7 +234,7 @@ sub configHelp
             # Find longest command length
             my $iCommandLength = 0;
 
-            foreach my $strCommand (sort(keys($$oConfigHelpData{&CONFIG_HELP_COMMAND})))
+            foreach my $strCommand (sort(keys(%{$$oConfigHelpData{&CONFIG_HELP_COMMAND}})))
             {
                 if (length($strCommand) > $iCommandLength)
                 {
@@ -243,7 +243,7 @@ sub configHelp
             }
 
             # Output commands
-            foreach my $strCommand (sort(keys($$oConfigHelpData{&CONFIG_HELP_COMMAND})))
+            foreach my $strCommand (sort(keys(%{$$oConfigHelpData{&CONFIG_HELP_COMMAND}})))
             {
                 my $oCommand = $$oConfigHelpData{&CONFIG_HELP_COMMAND}{$strCommand};
 
@@ -270,7 +270,7 @@ sub configHelp
 
             if (defined($$oCommand{&CONFIG_HELP_OPTION}))
             {
-                foreach my $strOption (sort(keys($$oCommand{&CONFIG_HELP_OPTION})))
+                foreach my $strOption (sort(keys(%{$$oCommand{&CONFIG_HELP_OPTION}})))
                 {
                     if (length($strOption) > $iOptionLength)
                     {
@@ -283,13 +283,13 @@ sub configHelp
                 }
 
                 # Iterate sections
-                foreach my $strSection (sort(keys($oSection)))
+                foreach my $strSection (sort(keys(%{$oSection})))
                 {
                     $strHelp .=
                         "\n\n" . ucfirst($strSection) . " Options:\n";
 
                     # Iterate options
-                    foreach my $strOption (sort(keys($$oSection{$strSection})))
+                    foreach my $strOption (sort(keys(%{$$oSection{$strSection}})))
                     {
                         $strHelp .= "\n";
 

lib/BackRest/Config/ConfigHelpData.pm

@@ -3,7 +3,7 @@
 #
 # This module is automatically generated by doc.pl and should never be manually edited.
 ####################################################################################################################################
-package BackRest::Config::Config::ConfigHelpData;
+package BackRest::Config::ConfigHelpData;
 
 use strict;
 use warnings FATAL => qw(all);

test/lib/BackRestTest/CommonTest.pm

@@ -90,6 +90,7 @@ my $strModule;
 my $strModuleTest;
 my $iModuleTestRun;
 my $bValidWalChecksum;
+my $bNormalLog;
 
 ####################################################################################################################################
 # BackRestTestCommon_ClusterStop
@@ -179,6 +180,7 @@ sub BackRestTestCommon_Run
     my $strModuleParam = shift;
     my $strModuleTestParam = shift;
     my $bValidWalChecksumParam = shift;
+    my $bNormalLogParam = shift;
 
     # &log(INFO, "module " . (defined($strModule) ? $strModule : ''));
     BackRestTestCommon_TestLog();
@@ -204,6 +206,7 @@ sub BackRestTestCommon_Run
     $strModuleTest = $strModuleTestParam;
     $iModuleTestRun = $iRun;
     $bValidWalChecksum = defined($bValidWalChecksumParam) ? $bValidWalChecksumParam : true;
+    $bNormalLog = defined($bNormalLogParam) ? $bNormalLogParam : true;
 
     return true;
 }
@@ -442,6 +445,9 @@ sub BackRestTestCommon_ExecuteRegExpAll
         $strLine =~ s/$strTestPath/[TEST_PATH]/g;
     }
 
+    $strLine = BackRestTestCommon_ExecuteRegExp($strLine, 'BACKREST_NAME_VERSION', '^' . BACKREST_NAME . ' ' . BACKREST_VERSION,
+                                                undef, false);
+
     $strLine = BackRestTestCommon_ExecuteRegExp($strLine, 'MODIFICATION-TIME', 'lModificationTime = [0-9]+', '[0-9]+$');
     $strLine = BackRestTestCommon_ExecuteRegExp($strLine, 'TIMESTAMP', 'timestamp"[ ]{0,1}:[ ]{0,1}[0-9]+','[0-9]+$');
 
@@ -534,15 +540,22 @@ sub BackRestTestCommon_ExecuteEnd
 
                 if ($bFullLog)
                 {
-                    $strLine =~ s/^[0-9]{4}-[0-1][0-9]-[0-3][0-9] [0-2][0-9]:[0-6][0-9]:[0-6][0-9]\.[0-9]{3} T[0-9]{2} //;
+                    if ($bNormalLog)
-
-                    if ($strLine !~ /^  TEST/)
                     {
-                        $strLine =~ s/^                            //;
+                        $strLine =~ s/^[0-9]{4}-[0-1][0-9]-[0-3][0-9] [0-2][0-9]:[0-6][0-9]:[0-6][0-9]\.[0-9]{3} T[0-9]{2} //;
-                        $strLine =~ s/^ //;
+                    }
-                        $strLine =~ s/\r$//;
+
+                    if ($strLine !~ /^  TEST/ || !$bNormalLog)
+                    {
+                        if ($bNormalLog)
+                        {
+                            $strLine =~ s/^                            //;
+                            $strLine =~ s/^ //;
+                            $strLine =~ s/\r$//;
+                        }
 
                         $strLine = BackRestTestCommon_ExecuteRegExpAll($strLine);
+
                         $strFullLog .= $strLine;
                     }
                 }

test/lib/BackRestTest/HelpTest.pm

@@ -0,0 +1,81 @@
+#!/usr/bin/perl
+####################################################################################################################################
+# HelpTest.pm - Unit Tests for help
+####################################################################################################################################
+package BackRestTest::HelpTest;
+
+####################################################################################################################################
+# Perl includes
+####################################################################################################################################
+use strict;
+use warnings FATAL => qw(all);
+use Carp qw(confess);
+
+use Exporter qw(import);
+use File::Basename qw(dirname);
+
+use lib dirname($0) . '/../lib';
+use BackRest::Common::Log;
+use BackRest::Config::Config;
+
+use BackRestTest::CommonTest;
+
+####################################################################################################################################
+# BackRestTestHelp_ExecuteHelp
+####################################################################################################################################
+sub BackRestTestHelp_ExecuteHelp
+{
+    my $strCommand = shift;
+
+    BackRestTestCommon_Execute(BackRestTestCommon_CommandMainAbsGet() . ' --no-config ' . $strCommand);
+}
+
+####################################################################################################################################
+# BackRestTestHelp_Test
+####################################################################################################################################
+our @EXPORT = qw(BackRestTestHelp_Test);
+
+sub BackRestTestHelp_Test
+{
+    my $strTest = shift;
+
+    # Setup test variables
+    my $iRun;
+    my $strModule = 'help';
+
+    # Print test banner
+    &log(INFO, 'HELP MODULE *****************************************************************');
+
+    #-------------------------------------------------------------------------------------------------------------------------------
+    # Test config
+    #-------------------------------------------------------------------------------------------------------------------------------
+    my $strThisTest = 'help';
+
+    if ($strTest eq 'all' || $strTest eq $strThisTest)
+    {
+        $iRun = 0;
+
+        &log(INFO, "Test help\n");
+
+        BackRestTestCommon_Drop(true);
+        BackRestTestCommon_Create();
+
+        # Increment the run, log, and decide whether this unit test should be run
+        if (BackRestTestCommon_Run(++$iRun, 'base', $strModule, $strThisTest, undef, false))
+        {
+            BackRestTestHelp_ExecuteHelp('help');
+            BackRestTestHelp_ExecuteHelp('help version');
+            BackRestTestHelp_ExecuteHelp('help --output=json --stanza=main info');
+            BackRestTestHelp_ExecuteHelp('help --output=json --stanza=main info output');
+        }
+
+        # Cleanup
+        if (BackRestTestCommon_Cleanup())
+        {
+            &log(INFO, 'cleanup');
+            BackRestTestCommon_Drop(true);
+        }
+    }
+}
+
+1;

test/log/help-help-001.log

@@ -0,0 +1,86 @@
+run 001 - base
+==============
+
+> [BACKREST_BIN] --no-config help
+------------------------------------------------------------------------------------------------------------------------------------
+[BACKREST_NAME_VERSION] - General help
+
+Usage:
+    pg_backrest [options] [command]
+
+Commands:
+    archive-get   Get a WAL segment from the archive.
+    archive-push  Push a WAL segment to the archive.
+    backup        Backup a database cluster.
+    expire        Expire backups that exceed retention.
+    help          Get help.
+    info          Retrieve information about backups.
+    restore       Restore a database cluster.
+    version       Get version.
+
+Use 'pg_backrest help [command]' for more information.
+
+> [BACKREST_BIN] --no-config help version
+------------------------------------------------------------------------------------------------------------------------------------
+[BACKREST_NAME_VERSION] - 'version' command help
+
+Get version.
+
+Displays installed pgBackRest version.
+
+> [BACKREST_BIN] --no-config help --output=json --stanza=main info
+------------------------------------------------------------------------------------------------------------------------------------
+[BACKREST_NAME_VERSION] - 'info' command help
+
+Retrieve information about backups.
+
+The info command operates on a single stanza or all stanzas.  Text output is
+the default and gives a human-readable summary of backups for the stanza(s)
+requested.  This format is subject to change with any release.
+
+For machine-readable output use --output=json.  The JSON output contains far
+more information than the text output, however this feature is currently
+experimental so the format may change between versions.
+
+Command Options:
+
+  --backup-host             backup host when operating remotely via SSH
+  --backup-user             backup host user when backup-host is set
+  --output                  output format [current=json, default=text]
+
+General Options:
+
+  --buffer-size             buffer size for file operations [default=4194304]
+  --cmd-remote              pgBackRest exe path on the remote host
+                            [default=[BACKREST_BIN]]
+  --compress-level          compression level for stored files [default=6]
+  --compress-level-network  compression level for network transfer when
+                            compress=n [default=3]
+  --config                  pgBackRest configuration file
+                            [default=/etc/pg_backrest.conf]
+  --repo-path               repository path where WAL segments, backups, logs,
+                            etc are stored [default=/var/lib/backup]
+  --repo-remote-path        remote repository path where WAL segments, backups,
+                            logs, etc are stored
+  --stanza                  command stanza [current=main]
+
+Log Options:
+
+  --log-level-console       level for console logging [default=warn]
+  --log-level-file          level for file logging [default=info]
+
+Use 'pg_backrest help info [option]' for more information.
+
+> [BACKREST_BIN] --no-config help --output=json --stanza=main info output
+------------------------------------------------------------------------------------------------------------------------------------
+[BACKREST_NAME_VERSION] - 'info' command - 'output' option help
+
+Output format.
+
+The following output types are supported:
+
+* text - Human-readable summary of backup information.
+* json - Exhaustive machine-readable backup information in JSON format.
+
+current: json
+default: text

test/test.pl

@@ -30,6 +30,7 @@ use BackRestTest::CommonTest;
 use BackRestTest::CompareTest;
 use BackRestTest::ConfigTest;
 use BackRestTest::FileTest;
+use BackRestTest::HelpTest;
 # use BackRestTest::IniTest;
 
 ####################################################################################################################################
@@ -270,6 +271,11 @@ eval
             #     BackRestTestIni_Test($strModuleTest);
             # }
 
+            if ($strModule eq 'all' || $strModule eq 'help')
+            {
+                BackRestTestHelp_Test($strModuleTest);
+            }
+
             if ($strModule eq 'all' || $strModule eq 'config')
             {
                 BackRestTestConfig_Test($strModuleTest);