item: add new --total-quality option to filter items according to their total quality

changelog.txt

@@ -31,6 +31,7 @@ Template for new versions:
 - `resize-armor`: resize armor or clothing item to any creature size.
 
 ## New Features
+- `item`: new ``--total-quality`` option for use in conjunction with ``--min-quality`` or ``--max-quality`` to filter items according to their total quality
 
 ## Fixes
 

docs/item.rst

@@ -49,7 +49,8 @@ Examples
     flood-fill to create a burrow covering an entire cavern layer).
 
 ``item melt -t weapon -m steel --max-quality 3``
-    Designate all steel weapons whose quality is at most superior for melting.
+    Designate all steel weapons whose core quality is at most superior for
+    melting.
 
 ``item hide -t boulder --scattered``
     Hide all scattered boulders, i.e. those that are not in stockpiles.
@@ -121,6 +122,11 @@ Options
     Only include items whose quality level is at most ``integer``. Useful
     values are 0 (ordinary) to 5 (masterwork).
 
+``--total-quality``
+    Only applies to ``--min-quality`` and ``--max-quality`` options. Filter items
+    according to their total quality (to include improvements) of instead of
+    their core quality.
+
 ``--stockpiled``
     Only include items that are in stockpiles. Does not include empty bins,
     barrels, and wheelbarrows assigned as storage and transport for stockpiles.
@@ -201,8 +207,12 @@ the filter is described.
     see above).
 
 * ``condition_quality(tab, lower, upper, negate)``
-    Selects items with quality between ``lower`` and ``upper`` (Range 0-5, see
-    above).
+    Selects items with core quality between ``lower`` and ``upper`` (Range 0-5,
+    see above).
+
+* ``condition_overall_quality(tab, lower, upper, negate)``
+    Selects items with total quality between ``lower`` and ``upper`` (Range 0-5,
+    see above).
 
 * ``condition_stockpiled(tab, negate)``
     Corresponds to ``--stockpiled``.

item.lua

@@ -145,6 +145,15 @@ function condition_quality(tab, lower, upper, negate)
     addPositiveOrNegative(tab, pred, negate)
 end
 
+--- @param tab conditions
+--- @param lower number # range: 0 (standard) to 5 (masterwork)
+--- @param upper number # range: 0 (standard) to 5 (masterwork)
+--- @param negate { negate : boolean }|nil
+function condition_overall_quality(tab, lower, upper, negate)
+    local pred = function(item) return lower <= item:getOverallQuality() and item:getOverallQuality() <= upper end
+    addPositiveOrNegative(tab, pred, negate)
+end
+
 --- @param tab conditions
 --- @param negate { negate : boolean }|nil
 function condition_forbid(tab, negate)
@@ -346,11 +355,15 @@ local options = {
     owned = false,
     nowebs = false,
     verbose = false,
+    filterquality = false,
+    totalquality = false,
 }
 
 --- @type (fun(item:item):boolean)[]
 local conditions = {}
 
+local minQuality, maxQuality = 0, 5
+
 local function flagsFilter(args, negate)
     local flags = argparse.stringList(args, "flag list")
     for _,flag in ipairs(flags) do
@@ -375,6 +388,7 @@ local positionals = argparse.processArgsGetopt({ ... }, {
   { nil, 'ignore-webs', handler = function() options.nowebs = true end },
   { 'n', 'dry-run', handler = function() options.dryrun = true end },
   { nil, 'by-type', handler = function() options.bytype = true end },
+  { nil, 'total-quality', handler = function() options.totalquality = true end },
   { 'i', 'inside', hasArg = true,
     handler = function (name)
         local burrow = dfhack.burrows.findByName(name,true)
@@ -407,14 +421,18 @@ local positionals = argparse.processArgsGetopt({ ... }, {
     handler = function(levelst)
         local level = argparse.nonnegativeInt(levelst, 'max-wear')
         condition_wear(conditions, 0, level) end },
+  -- Need to process total-quality argument before processing min/max-quality arguments,
+  -- since there's no guarantee the user will call total-quality first in the command line.
   { 'q', 'min-quality', hasArg = true,
     handler = function(levelst)
         local level = argparse.nonnegativeInt(levelst, 'min-quality')
-        condition_quality(conditions, level, 5) end },
+        minQuality = level options.filterquality = true end },
+        -- condition_quality(conditions, level, 5) end },
   { 'Q', 'max-quality', hasArg = true,
     handler = function(levelst)
         local level = argparse.nonnegativeInt(levelst, 'max-quality')
-        condition_quality(conditions, 0, level) end },
+        maxQuality = level options.filterquality = true end },
+        -- condition_quality(conditions, 0, level) end },
   { nil, 'stockpiled',
     handler = function () condition_stockpiled(conditions) end },
   { nil, 'scattered',
@@ -432,6 +450,14 @@ if options.help or positionals[1] == 'help' then
     return
 end
 
+if options.filterquality then
+    if options.totalquality then
+        condition_overall_quality(conditions, minQuality, maxQuality)
+    else
+        condition_quality(conditions, minQuality, maxQuality)
+    end
+end
+
 for i=2,#positionals do
     condition_description(conditions, positionals[i])
 end