improved -help action

Signed-off-by: Ken Museth <ken.museth@gmail.com>

Author: kmuseth

openvdb_cmd/vdb_tool/README.md

@@ -563,6 +563,19 @@ vdb_tool -help
 vdb_tool -help read write
 ```
 
+## Searching for an action by keyword
+Lists every action whose name or documentation contains the (case-insensitive) keyword, so you can discover the right action without scrolling the full help. Add `brief=true` for a compact, one-line-per-action listing.
+```
+vdb_tool -help search=mesh
+```
+
+## Did-you-mean suggestions for mistyped actions
+A mistyped action name — whether invoked directly or queried via `-help` — reports the closest known names instead of just failing:
+```
+vdb_tool -help mesh2sl     # -> Did you mean: "-mesh2ls" or "-mesh2sdf"?
+vdb_tool -sphre            # -> Did you mean: "-sphere"?
+```
+
 ## Getting help on all actions
 ```
 vdb_tool -eval help="*"

openvdb_cmd/vdb_tool/include/Parser.h

@@ -1712,7 +1712,22 @@ void Parser::usage(const VecS &actions, bool brief) const
 {
     for (const std::string &str : actions) {
         auto search = hashMap.find(str);
-        if (search == hashMap.end()) throw std::invalid_argument(iter->names[0]+": Parser:::usage: unsupported action \""+str+"\"\n");
+        if (search == hashMap.end()) {
+            // Mirror the "Did you mean ...?" suggestion the parser gives for a
+            // mistyped action on the command line, so "-help sphre" is as
+            // helpful as "-sphre".
+            // No action prefix here: the only caller (Tool::help) already
+            // prepends "help: " in its catch handler.
+            std::stringstream ss;
+            ss << "unsupported action \"" << str << "\"";
+            auto matches = this->closeMatches(str);
+            for (auto it = matches.begin(); it != matches.end();) {
+                ss << "\nDid you mean: \"-" << (it++)->second << "\"";
+                while (it != matches.end()) ss << " or \"-" << (it++)->second << "\"";
+                ss << "?";
+            }
+            throw std::invalid_argument(ss.str());
+        }
         std::clog << this->usage(*search->second, brief);
     }
 }// Parser::usage

openvdb_cmd/vdb_tool/include/Tool.h

@@ -597,6 +597,7 @@ void Tool::init()
     {{"actions", "", "read,write,...", "list of actions to document. If the list is empty documentation is printed for all available actions and if other actions proceed this action, documentation is printed for those actions only"},
      {"exit", "true", "1|0|true|false", "toggle wether to terminate after this action or not"},
      {"brief", "false", "1|0|true|false", "toggle brief or detailed documentation"},
+     {"search", "", "mesh", "case-insensitive keyword: list every action whose name or documentation contains it (e.g. search=mesh). Useful for discovering the right action without scrolling the full help."},
      {"format", "text", "text|md", "output format. 'text' (default) is the usual human-readable help; 'md' emits a single Markdown table of action names + descriptions, used to regenerate the action list in README.md so it can't drift from the registered actions."}},
      [](){}, [&](){this->help();}, 0); // anonymous options are appended to "actions"
 
@@ -1266,6 +1267,28 @@ void Tool::help()
     const bool stop = mParser.get<bool>("exit");
     const bool brief = mParser.get<bool>("brief");
     const std::string format = mParser.get<std::string>("format");
+    const std::string search = mParser.get<std::string>("search");
+
+    if (!search.empty()) {
+      // Discovery aid: list every action whose primary/alias name OR its
+      // documentation contains the (case-insensitive) keyword. Detailed usage
+      // is printed for each hit so the user sees the options too.
+      const std::string key = toLowerCase(search);
+      VecS hits;
+      for (const auto &a : mParser.available) {
+        bool match = contains(toLowerCase(a.documentation), key);
+        for (const auto &n : a.names) match = match || contains(toLowerCase(n), key);
+        if (match) hits.push_back(a.names[0]);
+      }
+      if (hits.empty()) {
+        std::clog << "help: no action matches keyword \"" << search << "\"\n";
+      } else {
+        std::clog << "Actions matching \"" << search << "\":\n";
+        mParser.usage(hits, brief);
+      }
+      if (stop) std::exit(EXIT_SUCCESS);
+      return;
+    }
 
     if (format == "md") {
       // Emit a single Markdown table of registered actions for the README's

pendingchanges/openvdb_cmd.txt

@@ -23,7 +23,7 @@ vdb_tool:
   - Action "-read" now supports ASCII XYZ point files (.xyz), where each line holds the x, y and z coordinates of a single point separated by whitespace. Blank lines and lines beginning with '#' are skipped as comments; any other line that does not parse as three numbers raises an error identifying the offending text. The points are accumulated as a vertex-only primitive (no faces), suitable for conversion to a VDB via -points2ls or -points2vdb. The data can also be streamed from standard input using the name "stdin.xyz".
   - Action "-mesh2ls/mesh2sdf" now supports generation of asymmetric narrow bands.
   - Improved error reporting when using unsupported actions and options.
-  - Actions can now have multiple names, e.g. "-read", "-import", "-load", "-i".
+  - Actions can now have multiple names (or aliases), e.g. "-read", "-import", "-load", "-i".
   - Added cutoff option to "-ls2fog" action.
   - Improved error reporting in vdb_tool (prints diagnostic error messages).
   - Improved error handling in vdb_tool (will recover from non-fatal errors).