Add "createitem inspect" subcommand

docs/Plugins.rst

@@ -2635,25 +2635,34 @@ Usage:
 
 createitem
 ==========
-Allows creating new items of arbitrary types and made of arbitrary materials.
-By default, items created are spawned at the feet of the selected unit.
+Allows creating new items of arbitrary types and made of arbitrary materials. A
+unit must be selected in-game to use this command. By default, items created are
+spawned at the feet of the selected unit.
 
 Specify the item and material information as you would indicate them in
 custom reaction raws, with the following differences:
 
 * Separate the item and material with a space rather than a colon
-* If the item has no subtype, omit the :NONE
-* If the item is REMAINS, FISH, FISH_RAW, VERMIN, PET, or EGG,
-  specify a CREATURE:CASTE pair instead of a material token.
+* If the item has no subtype, the ``:NONE`` can be omitted
+* If the item is ``REMAINS``, ``FISH``, ``FISH_RAW``, ``VERMIN``, ``PET``, or ``EGG``,
+  specify a ``CREATURE:CASTE`` pair instead of a material token.
 
 Corpses, body parts, and prepared meals cannot be created using this tool.
 
-Examples::
+To obtain the item and material tokens of an existing item, run
+``createitem inspect``. Its output can be passed directly as arguments to
+``createitem`` to create new matching items, as long as the item type is
+supported.
+
+Examples:
+
+* Create 2 pairs of steel gauntlets::
 
     createitem GLOVES:ITEM_GLOVES_GAUNTLETS INORGANIC:STEEL 2
-            Create 2 pairs of steel gauntlets.
+
+* Create tower-cap logs::
+
     createitem WOOD PLANT_MAT:TOWER_CAP:WOOD
-            Create tower-cap logs.
 
 For more examples, :wiki:`see this wiki page <Utility:DFHack/createitem>`.
 

docs/changelog.txt

@@ -38,6 +38,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 - `stockpiles`: fixed a crash when loading food stockpiles
 
 ## Misc Improvements
+- `createitem`: added an ``inspect`` subcommand to print the item and material tokens of existing items, which can be used to create additional matching items
 - `embark-assistant`: added support for searching for taller waterfalls (up to 50 z-levels tall)
 
 # 0.47.04-r2

plugins/createitem.cpp

@@ -53,9 +53,12 @@ DFhackCExport command_result plugin_init (color_ostream &out, std::vector<Plugin
         "                 PET, and EGG, replace this with a creature ID and caste.\n"
         "    [count] - How many of the item you wish to create.\n"
         "\n"
+        "To obtain the item and material of an existing item, run \n"
+        "'createitem inspect' with that item selected in-game.\n"
+        "\n"
         "To use this command, you must select which unit will create the items.\n"
         "By default, items created will be placed at that unit's feet.\n"
-        "To change this, type 'createitem <destination>'.\n"
+        "To change this, run 'createitem <destination>'.\n"
         "Valid destinations:\n"
         "* floor - Place items on floor beneath maker's feet.\n"
         "* item - Place items inside selected container.\n"
@@ -142,7 +145,21 @@ command_result df_createitem (color_ostream &out, vector <string> & parameters)
 
     if (parameters.size() == 1)
     {
-        if (parameters[0] == "floor")
+        if (parameters[0] == "inspect")
+        {
+            CoreSuspender suspend;
+            df::item *item = Gui::getSelectedItem(out);
+            if (!item)
+            {
+                return CR_FAILURE;
+            }
+
+            ItemTypeInfo iinfo(item->getType(), item->getSubtype());
+            MaterialInfo minfo(item->getMaterial(), item->getMaterialIndex());
+            out.print("%s %s\n", iinfo.getToken().c_str(), minfo.getToken().c_str());
+            return CR_OK;
+        }
+        else if (parameters[0] == "floor")
         {
             dest_container = -1;
             dest_building = -1;