Add "list" command to plant and regrass

* Add "plant list" and "regrass --list" to replace clunky commands

* Update Tags.rst: Add grass to "plants" tag description

docs/Tags.rst

@@ -42,7 +42,7 @@ for the tag assignment spreadsheet.
 - `labors <labors-tag-index>`: Tools that deal with labor assignment.
 - `map <map-tag-index>`: Tools that interact with the game map.
 - `military <military-tag-index>`: Tools that interact with the military.
-- `plants <plants-tag-index>`: Tools that interact with trees, shrubs, and crops.
+- `plants <plants-tag-index>`: Tools that interact with grass, trees, shrubs, and crops.
 - `stockpiles <stockpiles-tag-index>`: Tools that interact with stockpiles.
 - `units <units-tag-index>`: Tools that interact with units.
 - `workorders <workorders-tag-index>`: Tools that interact with workorders.

docs/changelog.txt

@@ -56,7 +56,7 @@ Template for new versions:
 
 ## New Features
 - `tweak`: ``named-codices``: display book titles instead of a material description in the stocks/trade screens
-- `plant` (formerly `plants`): can now ``remove`` shrubs and saplings; ``grow`` can make mature trees older; many new command options
+- `plant` (formerly `plants`): can now ``remove`` shrubs and saplings; ``list`` all valid shrub/sapling raw IDs; ``grow`` can make mature trees older; many new command options
 
 ## Fixes
 - `suspendmanager`: stop suspending single tile stair constructions
@@ -67,7 +67,7 @@ Template for new versions:
 - `blueprint`: capture track carving designations in addition to already-carved tracks
 - `changevein`: affect connected veins even outside of the selected map block
 - `logistics`: new ability to automatically forbid or claim items brought to a stockpile (or a dump within a stockpile)
-- `regrass`: now accepts numerical IDs for grass raws
+- `regrass`: now accepts numerical IDs for grass raws; ``regrass --list`` replaces ``regrass --plant ""``
 
 ## Documentation
 - `installing`: add instructions for how to use Steam DFHack with non-Steam DF (for DFHack auto-updates and cloud backups)

docs/plugins/plant.rst

@@ -5,9 +5,10 @@ plant
     :summary: Grow and remove shrubs or trees.
     :tags: adventure fort armok map plants
 
-Grow and remove shrubs or trees. Modes are ``create``, ``grow``, and ``remove``.
-``create`` allows the creation of new shrubs and saplings. ``grow`` adjusts the
-age of saplings and trees, allowing them to grow instantly. ``remove`` can
+Grow and remove shrubs or trees. Modes are ``list``, ``create``, ``grow``,
+and ``remove``. ``list`` prints a list of all valid shrub and sapling raw IDs.
+``create`` allows the creation of new shrubs and saplings. ``grow`` adjusts
+the age of saplings and trees, allowing them to grow instantly. ``remove`` can
 remove existing shrubs and saplings.
 
 Usage
@@ -19,16 +20,23 @@ Provide a mode (including a ``plant_id`` for ``create``) followed by optional
 in the form ``0,0,0``, without spaces. The string ``here`` can be used in place
 of numeric coordinates to use the position of the keyboard cursor, if active.
 
+::
+
+    plant list
+
+Prints a list of all shrub and sapling raw IDs for use with the other modes.
+Both numerical and string IDs are provided.
+
 ::
 
     plant create <plant_id> [<pos>] [<options>]
 
 Creates a new plant of the specified type at ``pos`` or the cursor position.
 The target must be a floor tile, consisting of soil, grass, ashes, or
-non-smooth muddy stone. ``plant_id`` is not case-sensitive, but must be
-enclosed in quotes if spaces exist. (No unmodded shrub or sapling IDs have
-spaces.) A numerical ID can also be used. Providing an empty string with ""
-will print all available IDs and skip plant creation.
+non-smooth muddy (layer, obsidian, or ore) stone. ``plant_id`` is not
+case-sensitive, but must be enclosed in quotes if spaces exist. (No unmodded
+shrub or sapling raw IDs have spaces.) A numerical ID can be used in place of a
+string. Use ``plant list`` for a list of valid IDs.
 
 ::
 
@@ -51,10 +59,10 @@ of fully-grown trees isn't currently supported.
 Examples
 --------
 
+``plant list``
+    List all valid shrub and sapling raw IDs.
 ``plant create tower_cap``
     Create a Tower Cap sapling at the cursor.
-``plant create ""``
-    List all valid shrub and sapling IDs.
 ``plant create 203 -c -a tree``
     Create a Willow sapling at the cursor, even away from water features,
     ready to mature into a tree.
@@ -109,11 +117,11 @@ Grow Options
     will stunt tree height. It may be more desirable to grow in stages rather
     than all at once. Trees grow taller every 10 years.)
 ``-f``, ``--filter <plant_id>[,<plant_id>...]``
-    Define a filter list of plant IDs to target, ignoring all other tree types.
-    ``plant_id`` is not case-sensitive, but must be enclosed in quotes if
-    spaces exist. (No unmodded tree IDs have spaces.) A numerical ID can also
-    be used. Use ``plant create ""`` and check under ``Saplings`` for a list
-    of valid IDs.
+    Define a filter list of plant raw IDs to target, ignoring all other tree
+    types. ``plant_id`` is not case-sensitive, but must be enclosed in quotes
+    if spaces exist. (No unmodded tree raw IDs have spaces.) A numerical ID
+    can be used in place of a string. Use ``plant list`` and check under
+    ``Saplings`` for a list of valid IDs.
 ``-e``, ``--exclude <plant_id>[,<plant_id>...]``
     Same as ``--filter``, but target everything except these. Cannot be used
     with ``--filter``.
@@ -134,15 +142,15 @@ Remove Options
 ``-p``, ``--saplings``
     Target saplings for removal.
 ``-d``, ``--dead``
-    Only target dead plants for removal. Can't be used without ``--shrubs`` or
-    ``--saplings``.
+    Only target dead plants for removal. Can't be used without ``--shrubs``
+    or ``--saplings``.
 ``-f``, ``--filter <plant_id>[,<plant_id>...]``
-    Define a filter list of plant IDs to target, ignoring all other plant types.
-    This applies after ``--shrubs`` and ``--saplings`` are targeted, and can't
-    be used without one of those options. ``plant_id`` is not case-sensitive,
-    but must be enclosed in quotes if spaces exist. (No unmodded shrub or
-    sapling IDs have spaces.) A numerical ID can also be used. Use
-    ``plant create ""`` for a list of valid IDs.
+    Define a filter list of plant raw IDs to target, ignoring all other plant
+    types. This applies after ``--shrubs`` and ``--saplings`` are targeted,
+    and can't be used without one of those options. ``plant_id`` is not
+    case-sensitive, but must be enclosed in quotes if spaces exist. (No
+    unmodded shrub or sapling raw IDs have spaces.) A numerical ID can be
+    used in place of a string. Use ``plant list`` for a list of valid IDs.
 ``-e``, ``--exclude <plant_id>[,<plant_id>...]``
     Same as ``--filter``, but target everything except these. Cannot be used
     with ``--filter``.

docs/plugins/regrass.rst

@@ -3,7 +3,7 @@ regrass
 
 .. dfhack-tool::
     :summary: Regrow surface grass and cavern moss.
-    :tags: adventure fort armok animals map
+    :tags: adventure fort armok animals map plants
 
 This command can refresh the grass (and subterranean moss) growing on your map.
 Operates on floors, stairs, and ramps. Also works underneath shrubs, saplings,
@@ -45,9 +45,10 @@ Examples
 ``regrass -f``
     Regrass the entire map, refilling existing and depleted grass, else filling
     with a randomly selected grass type if non-existent.
-``regrass -p ""``
-    Print all valid grass raw ids. Don't regrass.
-``regrass -zf -p underlichen``
+``regrass -l``
+    Print all valid grass raw IDs for use with ``--plant``. Both numerical and
+    string IDs are provided. This ignores all other options and skips regrass.
+``regrass -zf -p 128``
     Regrass the current z-level, refilling existing and depleted grass, else
     filling with ``underlichen`` if non-existent.
 ``regrass here -bnf -p "dog's tooth grass"``
@@ -59,6 +60,9 @@ Examples
 Options
 -------
 
+``-l``, ``--list``
+    Print all available grass raw IDs and skip regrass. For use with
+    ``--plant``.
 ``-m``, ``--max``
     Maxes out every grass type in the tile, giving extra grazing time.
     Not normal DF behavior. Tile will appear to be the first type of grass
@@ -79,10 +83,10 @@ Options
 ``-p``, ``--plant <grass_id>``
     Specify a grass type for the ``--force`` option. ``grass_id`` is not
     case-sensitive, but must be enclosed in quotes if spaces exist. A numerical
-    ID can also be used. Providing an empty string with "" will print all
-    available IDs and skip regrass.
+    ID can also be used.
 ``-a``, ``--ashes``
-    Regrass tiles that've been burnt to ash.
+    Regrass tiles that've been burnt to ash. Usually ash must revert to soil
+    first before grass can grow.
 ``-d``, ``--buildings``
     Regrass tiles under certain passable building tiles including stockpiles,
     planned buildings, workshops, and farms. (Farms will convert grass tiles to

plugins/lua/plant.lua

@@ -19,9 +19,7 @@ local function find_plant_idx(s) --find plant raw index by id string
 end
 
 local function find_plant(s) --accept index string or match id string
-    if s == '' then
-        return -2 --will print all non-grass ids (for create)
-    elseif tonumber(s) then
+    if tonumber(s) then
         return argparse.nonnegativeInt(s, 'plant_id')
     else
         return find_plant_idx(s)
@@ -50,7 +48,7 @@ local year_table =
     tree = 3, --sapling_to_tree_threshold
     ["1x1"] = 3,
     ["2x2"] = 201, --kapok, ginkgo, highwood
-    ["3x3"] = 401, --highwood
+    ["3x3"] = 401, --highwood (tower-cap is bugged)
 }
 
 local function plant_age(s) --tree stage or numerical value
@@ -98,7 +96,9 @@ function parse_commandline(opts, pos_1, pos_2, filter_vec, args)
 
     local p1 = positionals[1]
     if not p1 then
-        qerror('Specify mode: create, grow, or remove!')
+        qerror('Specify mode: list, create, grow, or remove!')
+    elseif p1 == 'list' then
+        opts.plant_idx = -2 --will print all non-grass IDs
     elseif p1 == 'create' then
         opts.create = true
 
@@ -112,7 +112,7 @@ function parse_commandline(opts, pos_1, pos_2, filter_vec, args)
     elseif p1 == 'remove' then
         opts.del = true
     else
-        qerror('Invalid mode: "'..p1..'"! Must be create, grow, or remove!')
+        qerror('Invalid mode: "'..p1..'"! Must be list, create, grow, or remove!')
     end
 
     local n = opts.create and 3 or 2

plugins/lua/regrass.lua

@@ -27,9 +27,10 @@ local function find_grass(s) --accept index string or match id string
 end
 
 function parse_commandline(opts, pos_1, pos_2, args)
-    local plant_str
+    local plant_str, do_list
     local positionals = argparse.processArgsGetopt(args,
     {
+        {'l', 'list', handler=function() do_list = true end},
         {'m', 'max', handler=function() opts.max_grass = true end},
         {'n', 'new', handler=function() opts.new_grass = true end},
         {'a', 'ashes', handler=function() opts.ashes = true end},
@@ -41,10 +42,10 @@ function parse_commandline(opts, pos_1, pos_2, args)
         {'p', 'plant', hasArg=true, handler=function(optarg) plant_str = optarg end},
     })
 
-    if plant_str then
-        if plant_str == '' then --will print all grass ids
-            opts.forced_plant = -2
-        elseif not opts.force then
+    if do_list then
+        opts.forced_plant = -2 --will print all grass IDs
+    elseif plant_str then
+        if not opts.force then
             qerror('Use of --plant without --force!')
         else
             opts.forced_plant = find_grass(plant_str)

plugins/plant.cpp

@@ -85,7 +85,7 @@ struct plant_options
     bool zlevel = false; // Operate on entire z-levels
     bool dry_run = false; // Don't actually grow or remove anything
 
-    int32_t plant_idx = -1; // Plant raw index of plant to create; -2 means print all non-grass ids
+    int32_t plant_idx = -1; // Plant raw index of plant to create; -2 means print all non-grass IDs
     int32_t age = -1; // Set plant to this age for grow/create; -1 for default
 
     static struct_identity _identity;
@@ -227,7 +227,7 @@ command_result df_createplant(color_ostream &out, const df::coord &pos, const pl
     auto p_raw = vector_get(world->raws.plants.all, options.plant_idx);
     if (!p_raw)
     {
-        out.printerr("Plant raw not found!\n");
+        out.printerr("Can't create plant: Plant raw not found!\n");
         return CR_FAILURE;
     }
 
@@ -525,6 +525,18 @@ command_result df_plant(color_ostream &out, vector<string> &parameters)
     {
         return CR_WRONG_USAGE;
     }
+    else if (options.plant_idx == -2)
+    {   // Print all non-grass raw IDs ("plant list")
+        out.print("--- Shrubs ---\n");
+        for (auto p_raw : world->raws.plants.bushes)
+            out.print("%d: %s\n", p_raw->index, p_raw->id.c_str());
+
+        out.print("\n--- Saplings ---\n");
+        for (auto p_raw : world->raws.plants.trees)
+            out.print("%d: %s\n", p_raw->index, p_raw->id.c_str());
+
+        return CR_OK;
+    }
     else if (options.force && !options.create)
     {
         out.printerr("Can't use --force without create!\n");
@@ -552,18 +564,6 @@ command_result df_plant(color_ostream &out, vector<string> &parameters)
         out.printerr("--trees not implemented!\n");
         return CR_FAILURE;
     }
-    else if (options.plant_idx == -2)
-    {   // Print all non-grass raw ids
-        out.print("--- Shrubs ---\n");
-        for (auto p_raw : world->raws.plants.bushes)
-            out.print("%d: %s\n", p_raw->index, p_raw->id.c_str());
-
-        out.print("\n--- Saplings ---\n");
-        for (auto p_raw : world->raws.plants.trees)
-            out.print("%d: %s\n", p_raw->index, p_raw->id.c_str());
-
-        return CR_OK;
-    }
 
     DEBUG(log, out).print("pos_1 = (%d, %d, %d)\npos_2 = (%d, %d, %d)\n",
         pos_1.x, pos_1.y, pos_1.z, pos_2.x, pos_2.y, pos_2.z);