empty-bin command options (recursive and liquid)

docs/empty-bin.rst

@@ -9,9 +9,6 @@ This tool can quickly empty the contents of the selected container (bin,
 barrel, pot, wineskin, quiver, etc.) onto the floor, allowing you to access
 individual items that might otherwise be hard to get to.
 
-Note that if there are liquids in the container, they will empty onto the floor
-and become unusable.
-
 If you instead select a stockpile or building, running `empty-bin` will empty
 *all* containers in the stockpile or building. Likewise, if you select a tile
 that has many items and the UI is showing the list of items, all containers on
@@ -22,4 +19,24 @@ Usage
 
 ::
 
-    empty-bin
+    empty-bin [<options>]
+
+Examples
+--------
+
+``empty-bin``
+    Empty the contents of selected containers or all containers in the selected stockpile or building, except containers with liquids, onto the floor.
+
+``empty-bin --liquids``
+    Empty the contents of selected containers or all containers in the selected stockpile or building, including containers with liquids, onto the floor.
+
+``empty-bin --recursive --liquids``
+    Empty the contents of selected containers or all containers in the selected stockpile or building, including containers with liquids and containers contents that are containers, such as a bags of seeds or filled waterskins, onto the floor.
+
+Options
+--------------
+
+``-r``, ``--recursive``
+    Recursively empty containers.
+``-l``, ``--liquids``
+    Move contained liquids (DRINK and LIQUID_MISC) to the floor, making them unusable.

empty-bin.lua

@@ -1,30 +1,53 @@
 -- Empty a bin onto the floor
--- Based on "emptybin" by StoneToad
+-- Based on 'emptybin' by StoneToad
 -- https://gist.github.com/stonetoad/11129025
 -- http://dwarffortresswiki.org/index.php/DF2014_Talk:Bin
 
-local function moveItem(item, to_pos)
-    print('  ' .. dfhack.items.getReadableDescription(item))
-    dfhack.items.moveToGround(item, to_pos)
-end
+local argparse = require('argparse')
+
+local options, args = {
+        help = false,
+        recursive = false,
+        liquids = false
+    },
+    {...}
 
 local function emptyContainer(container)
     local items = dfhack.items.getContainedItems(container)
-
     if #items > 0 then
         print('Emptying ' .. dfhack.items.getReadableDescription(container))
         local pos = xyz2pos(dfhack.items.getPosition(container))
         for _, item in ipairs(items) do
-            moveItem(item, pos)
+            local skip_liquid = item:getType() == df.item_type.LIQUID_MISC or item:getType() == df.item_type.DRINK and not options.liquids
+            if skip_liquid then
+                print('  ' .. dfhack.items.getReadableDescription(item) .. ' was skipped because the --liquids flag was not provided')
+            else
+                print('  ' .. dfhack.items.getReadableDescription(item))
+                dfhack.items.moveToGround(item, pos)
+                if options.recursive then
+                    emptyContainer(item)
+                end
+            end
         end
     end
 end
 
-local viewsheets = df.global.game.main_interface.view_sheets
+argparse.processArgsGetopt(args,{
+    { 'h', 'help', handler = function() options.help = true end },
+    { 'r', 'recursive', handler = function() options.recursive = true end },
+    { 'l', 'liquids', handler = function() options.liquids = true end }
+    })
 
+if options.help then
+    print(dfhack.script_help())
+    return
+end
+
+local viewsheets = df.global.game.main_interface.view_sheets
 local stockpile = dfhack.gui.getSelectedStockpile(true)
 local selectedItem = dfhack.gui.getSelectedItem(true)
 local selectedBuilding = dfhack.gui.getSelectedBuilding(true)
+
 if stockpile then
     local contents = dfhack.buildings.getStockpileContents(stockpile)
     for _, container in ipairs(contents) do
@@ -33,7 +56,9 @@ if stockpile then
 elseif selectedItem then
     emptyContainer(selectedItem)
 elseif selectedBuilding then
-    if not df.building_actual:is_instance(selectedBuilding) then return end
+    if not selectedBuilding:isActual() then
+        return
+    end
     for _, contained in ipairs(selectedBuilding.contained_items) do
         if contained.use_mode == df.building_item_role_type.TEMP then
             emptyContainer(contained.item)
@@ -45,5 +70,5 @@ elseif viewsheets.open then
         emptyContainer(item)
     end
 else
-    qerror("Please select a container, building, stockpile, or tile with a list of items.")
+    qerror('Please select a container, building, stockpile, or tile with a list of items.')
 end