list tools in categories with tags builtin

docs/builtins/tags.rst

@@ -2,15 +2,25 @@ tags
 ====
 
 .. dfhack-tool::
-    :summary: List the strings that DFHack tools can be tagged with.
+    :summary: List the categories of DFHack tools or the tools with those tags.
     :tags: dfhack
 
-You can find groups of related tools by passing the tag name to the `ls`
-command.
+DFHack tools are labeled with tags so you can find groups of related commands.
+This builtin command lists the tags that you can explore, or, if called with the
+name of a tag, lists the tools that have that tag.
 
 Usage
 -----
 
-::
+``tags``
+    List the categories of DFHack tools and a description of those categories.
+``tags <tag>``
+    List the tools that are tagged with the given tag.
 
-    tags
+Examples
+--------
+
+``tags``
+    List the defined tags.
+``tags design``
+    List all the tools that have the ``design`` tag.

library/Core.cpp

@@ -600,7 +600,7 @@ void help_helper(color_ostream &con, const string &entry_name) {
     }
 }
 
-void tags_helper(color_ostream &con) {
+void tags_helper(color_ostream &con, const string &tag) {
     CoreSuspender suspend;
     auto L = Lua::Core::State;
     Lua::StackUnwinder top(L);
@@ -611,7 +611,9 @@ void tags_helper(color_ostream &con) {
         return;
     }
 
-    if (!Lua::SafeCall(con, L, 0, 0)) {
+    Lua::Push(L, tag);
+
+    if (!Lua::SafeCall(con, L, 1, 0)) {
         con.printerr("Failed Lua call to helpdb.tags.\n");
     }
 }
@@ -712,7 +714,7 @@ command_result Core::runCommand(color_ostream &con, const std::string &first_, v
     }
     else if (first == "tags")
     {
-        tags_helper(con);
+        tags_helper(con, parts.size() ? parts[0] : "");
     }
     else if (first == "load" || first == "unload" || first == "reload")
     {

library/lua/helpdb.lua

@@ -719,14 +719,6 @@ local function print_columns(col1text, col2text)
     end
 end
 
--- implements the 'tags' builtin command
-function tags()
-    local tags = get_tags()
-    for _,tag in ipairs(tags) do
-        print_columns(tag, get_tag_data(tag).description)
-    end
-end
-
 -- prints the requested entries to the console. include and exclude filters are
 -- defined as in search_entries() above.
 local function list_entries(skip_tags, include, exclude)
@@ -764,4 +756,27 @@ function ls(filter_str, skip_tags, show_dev_commands)
                  show_dev_commands and {} or {tag='dev'})
 end
 
+local function list_tags()
+    local tags = get_tags()
+    for _,tag in ipairs(tags) do
+        print_columns(tag, get_tag_data(tag).description)
+    end
+end
+
+-- implements the 'tags' builtin command
+function tags(tag)
+    if tag and #tag > 0 and not is_tag(tag) then
+        dfhack.printerr(('unrecognized tag: "%s"'):format(tag))
+    end
+
+    if not is_tag(tag) then
+        list_tags()
+        return
+    end
+
+    local skip_tags = true
+    local include = {entry_type={ENTRY_TYPES.COMMAND}, tag=tag}
+    list_entries(skip_tags, include)
+end
+
 return _ENV

test/library/helpdb.lua

@@ -622,6 +622,20 @@ function test.tags()
     end)
 end
 
+function test.tags_tag()
+    local mock_print = mock.func()
+    mock.patch(h, 'print', mock_print, function()
+        h.tags('armok')
+        expect.eq(3, mock_print.call_count)
+        expect.eq('bindboxers           Bind your boxers.',
+            mock_print.call_args[1][1])
+        expect.eq('boxbinders           Box your binders.',
+            mock_print.call_args[2][1])
+        expect.eq('samename             Samename.',
+            mock_print.call_args[3][1])
+    end)
+end
+
 function test.ls()
     local mock_print = mock.func()
     mock.patch(h, 'print', mock_print, function()