QPDFArgParser: support adding/printing help information

11 files changed, 151 insertions, 49 deletions

diff --git a/libtests/arg_parser.cc b/libtests/arg_parser.cc
index 3da0206e..340bd8d4 100644
--- a/libtests/arg_parser.cc
+++ b/libtests/arg_parser.cc
@@ -68,6 +68,18 @@ ArgParser::initOptions()
     ap.addBare("sheep", [this](){ this->ap.selectOptionTable("sheep"); });
     ap.registerOptionTable("sheep", nullptr);
     ap.copyFromOtherTable("ewe", "baaa");
+
+    ap.addHelpFooter("For more help, read the manual.\n");
+    ap.addHelpTopic(
+        "quack", "Quack Options",
+        "Just put stuff after quack to get a count at the end.\n");
+    ap.addHelpTopic(
+        "baaa", "Baaa Options",
+        "Ewe can do sheepish things.\n"
+        "For example, ewe can add more ram to your computer.\n");
+    ap.addOptionHelp("--ewe", "baaa",
+                     "just for ewe", "You are not a ewe.\n");
+    ap.addOptionHelp("--ram", "baaa", "curly horns", "");
 }
 
 void
@@ -152,62 +164,60 @@ ArgParser::finalChecks()
 void
 ArgParser::test_exceptions()
 {
-    try
-    {
+    auto err = [](char const* msg, std::function<void()> fn) {
+        try
+        {
+            fn();
+            assert(msg == nullptr);
+        }
+        catch (std::exception& e)
+        {
+            std::cout << msg << ": " << e.what() << std::endl;
+        }
+    };
+
+    err("duplicate handler", [this]() {
         ap.selectMainOptionTable();
         ap.addBare("potato", [](){});
-        assert(false);
-    }
-    catch (std::exception& e)
-    {
-        std::cout << "duplicate handler: " << e.what() << std::endl;
-    }
-    try
-    {
+    });
+    err("duplicate handler", [this]() {
         ap.selectOptionTable("baaa");
         ap.addBare("ram", [](){});
-        assert(false);
-    }
-    catch (std::exception& e)
-    {
-        std::cout << "duplicate handler: " << e.what() << std::endl;
-    }
-    try
-    {
+    });
+    err("duplicate table", [this]() {
         ap.registerOptionTable("baaa", nullptr);
-        assert(false);
-    }
-    catch (std::exception& e)
-    {
-        std::cout << "duplicate table: " << e.what() << std::endl;
-    }
-    try
-    {
+    });
+    err("unknown table", [this]() {
         ap.selectOptionTable("aardvark");
-        assert(false);
-    }
-    catch (std::exception& e)
-    {
-        std::cout << "unknown table: " << e.what() << std::endl;
-    }
-    try
-    {
+    });
+    err("copy from unknown table", [this]() {
         ap.copyFromOtherTable("one", "two");
-        assert(false);
-    }
-    catch (std::exception& e)
-    {
-        std::cout << "copy from unknown table: " << e.what() << std::endl;
-    }
-    try
-    {
+    });
+    err("copy unknown from other table", [this]() {
         ap.copyFromOtherTable("two", "baaa");
-        assert(false);
-    }
-    catch (std::exception& e)
-    {
-        std::cout << "copy unknown from other table: " << e.what() << std::endl;
-    }
+    });
+    err("add existing help topic", [this]() {
+        ap.addHelpTopic("baaa", "potato", "salad");
+    });
+    err("add reserved help topic", [this]() {
+        ap.addHelpTopic("all", "potato", "salad");
+    });
+    err("add to unknown topic", [this]() {
+        ap.addOptionHelp("--new", "oops", "potato", "salad");
+    });
+    err("bad option for help", [this]() {
+        ap.addOptionHelp("nodash", "baaa", "potato", "salad");
+    });
+    err("bad topic for help", [this]() {
+        ap.addHelpTopic("--dashes", "potato", "salad");
+    });
+    err("duplicate option help", [this]() {
+        ap.addOptionHelp("--ewe", "baaa", "potato", "salad");
+    });
+    err("invalid choice handler to unknown", [this]() {
+        ap.addInvalidChoiceHandler(
+            "elephant", [](char*){});
+    });
 }
 
 int main(int argc, char* argv[])
diff --git a/libtests/libtests.testcov b/libtests/libtests.testcov
index 69573ab0..70aae578 100644
--- a/libtests/libtests.testcov
+++ b/libtests/libtests.testcov
@@ -54,3 +54,10 @@ QPDFArgParser unrecognized 0
 QPDFArgParser complete choices 0
 QPDFArgParser copy from unknown 0
 QPDFArgParser copy unknown 0
+QPDFArgParser add reserved help topic 0
+QPDFArgParser add existing topic 0
+QPDFArgParser add to unknown topic 0
+QPDFArgParser duplicate option help 0
+QPDFArgParser bad option for help 0
+QPDFArgParser bad topic for help 0
+QPDFArgParser invalid choice handler to unknown 0
diff --git a/libtests/qtest/arg_parser.test b/libtests/qtest/arg_parser.test
index 1d24d507..5079289a 100644
--- a/libtests/qtest/arg_parser.test
+++ b/libtests/qtest/arg_parser.test
@@ -101,4 +101,30 @@ $td->runtest("args from stdin",
              {$td->FILE => "stdin.out", $td->EXIT_STATUS => 0},
              $td->NORMALIZE_NEWLINES);
 
-$td->report(2 + (2 * scalar(@completion_tests)) + scalar(@arg_tests));
+my @help_tests = (
+    '',
+    '=all',
+    '=--ewe',
+    '=quack',
+    );
+foreach my $i (@help_tests)
+{
+    my $out = $i;
+    $out =~ s/[=-]//g;
+    if ($out ne '')
+    {
+        $out = "-$out";
+    }
+    $td->runtest("--help$i",
+                 {$td->COMMAND => "arg_parser --help$i"},
+                 {$td->FILE => "help$out.out", $td->EXIT_STATUS => 0},
+                 $td->NORMALIZE_NEWLINES);
+}
+
+$td->runtest("bad help option",
+             {$td->COMMAND => 'arg_parser --help=--oops'},
+             {$td->FILE => "help-bad.out", $td->EXIT_STATUS => 2},
+             $td->NORMALIZE_NEWLINES);
+
+$td->report(3 + (2 * scalar(@completion_tests)) +
+            scalar(@arg_tests) + scalar(@help_tests));
diff --git a/libtests/qtest/arg_parser/completion-top-arg-zsh.out b/libtests/qtest/arg_parser/completion-top-arg-zsh.out
index 5a500d38..5c159957 100644
--- a/libtests/qtest/arg_parser/completion-top-arg-zsh.out
+++ b/libtests/qtest/arg_parser/completion-top-arg-zsh.out
@@ -2,7 +2,9 @@
 --completion-zsh
 --help
 --help=
+--help=--ewe
 --help=all
+--help=quack
 --moo
 --moo=
 --oink=
diff --git a/libtests/qtest/arg_parser/completion-top-arg.out b/libtests/qtest/arg_parser/completion-top-arg.out
index 4e69efbd..db3d4b0a 100644
--- a/libtests/qtest/arg_parser/completion-top-arg.out
+++ b/libtests/qtest/arg_parser/completion-top-arg.out
@@ -1,5 +1,7 @@
 --baaa
 --completion-zsh
+--help
+--help=
 --moo
 --moo=
 --oink=
diff --git a/libtests/qtest/arg_parser/exceptions.out b/libtests/qtest/arg_parser/exceptions.out
index 82eef2a7..eb8dbe8a 100644
--- a/libtests/qtest/arg_parser/exceptions.out
+++ b/libtests/qtest/arg_parser/exceptions.out
@@ -4,3 +4,10 @@ duplicate table: QPDFArgParser: registering already registered option table baaa
 unknown table: QPDFArgParser: selecting unregistered option table aardvark
 copy from unknown table: QPDFArgParser: attempt to copy from unknown table two
 copy unknown from other table: QPDFArgParser: attempt to copy unknown argument two from table baaa
+add existing help topic: QPDFArgParser: topic baaa has already been added
+add reserved help topic: QPDFArgParser: can't register reserved help topic all
+add to unknown topic: QPDFArgParser: unable to add option --new to unknown help topic oops
+bad option for help: QPDFArgParser: options for help must start with --
+bad topic for help: QPDFArgParser: help topics must not start with -
+duplicate option help: QPDFArgParser: option --ewe already has help
+invalid choice handler to unknown: QPDFArgParser: attempt to add invalid choice handler to unknown argument
diff --git a/libtests/qtest/arg_parser/help-all.out b/libtests/qtest/arg_parser/help-all.out
new file mode 100644
index 00000000..432d4afb
--- /dev/null
+++ b/libtests/qtest/arg_parser/help-all.out
@@ -0,0 +1,32 @@
+Run "arg_parser --help=topic" for help on a topic.
+Run "arg_parser --help=option" for help on an option.
+Run "arg_parser --help=all" to see all available help.
+
+Topics:
+  baaa: Baaa Options
+  quack: Quack Options
+
+== topic baaa (Baaa Options) ==
+
+Ewe can do sheepish things.
+For example, ewe can add more ram to your computer.
+
+Related options:
+  --ewe: just for ewe
+  --ram: curly horns
+
+== topic quack (Quack Options) ==
+
+Just put stuff after quack to get a count at the end.
+
+== option --ewe (just for ewe) ==
+
+You are not a ewe.
+
+== option --ram (curly horns) ==
+
+curly horns
+
+====
+
+For more help, read the manual.
diff --git a/libtests/qtest/arg_parser/help-bad.out b/libtests/qtest/arg_parser/help-bad.out
new file mode 100644
index 00000000..e9d753b2
--- /dev/null
+++ b/libtests/qtest/arg_parser/help-bad.out
@@ -0,0 +1 @@
+usage: unknown help option --oops
diff --git a/libtests/qtest/arg_parser/help-ewe.out b/libtests/qtest/arg_parser/help-ewe.out
new file mode 100644
index 00000000..7fe4bb0e
--- /dev/null
+++ b/libtests/qtest/arg_parser/help-ewe.out
@@ -0,0 +1,3 @@
+You are not a ewe.
+
+For more help, read the manual.
diff --git a/libtests/qtest/arg_parser/help-quack.out b/libtests/qtest/arg_parser/help-quack.out
new file mode 100644
index 00000000..b114471e
--- /dev/null
+++ b/libtests/qtest/arg_parser/help-quack.out
@@ -0,0 +1,3 @@
+Just put stuff after quack to get a count at the end.
+
+For more help, read the manual.
diff --git a/libtests/qtest/arg_parser/help.out b/libtests/qtest/arg_parser/help.out
new file mode 100644
index 00000000..0accbe67
--- /dev/null
+++ b/libtests/qtest/arg_parser/help.out
@@ -0,0 +1,9 @@
+Run "arg_parser --help=topic" for help on a topic.
+Run "arg_parser --help=option" for help on an option.
+Run "arg_parser --help=all" to see all available help.
+
+Topics:
+  baaa: Baaa Options
+  quack: Quack Options
+
+For more help, read the manual.