Add instruments script and documentation

Author: unboundlopez

docs/instruments.rst

@@ -26,6 +26,9 @@ Usage
 
     instruments [list]
     instruments order <instrument_name> [<quantity>] [<options>]
+    instruments all <quantity> [<options>]
+    instruments handheld <quantity> [<options>]
+    instruments building <quantity> [<options>]
 
 When ordering, the default is to order one of the specified instrument
 (including all of its components).
@@ -43,6 +46,14 @@ Examples
 ``instruments order ilul``
     Creates work orders to assemble one ïlul. Spelling does not need to include
     the special ï character.
+``instruments all 5``
+    Creates work orders to produce five of every instrument available to your
+    civilization.
+``instruments handheld 2``
+    Creates work orders to produce two of each handheld instrument.
+``instruments building 3``
+    Creates work orders to produce three of each instrument that is placed as a
+    building.
 
 Options
 -------

instruments.lua

@@ -137,6 +137,24 @@ local function order_instrument(name, amount, quiet)
     end
 end
 
+local function order_instruments(filter_fn, amount, quiet)
+    local matched = {}
+
+    for _, instr in ipairs(raws.itemdefs.instruments) do
+        if instr.source_enid == civ_id and filter_fn(instr) then
+            table.insert(matched, instr)
+        end
+    end
+
+    if #matched == 0 then
+        qerror("No instruments matched the selection")
+    end
+
+    for _, instr in ipairs(matched) do
+        order_instrument(dfhack.toSearchNormalized(instr.name), amount, quiet)
+    end
+end
+
 local help = false
 local quiet = false
 local positionals = argparse.processArgsGetopt({...}, {
@@ -159,4 +177,14 @@ elseif positionals[1] == "order" then
 
     local amount = positionals[3] or 1
     order_instrument(instrument_name, amount, quiet)
+elseif positionals[1] == "all" then
+    local amount = positionals[2] or 1
+    order_instruments(function() return true end, amount, quiet)
+elseif positionals[1] == "handheld" then
+    local amount = positionals[2] or 1
+    order_instruments(function(instr) return not instr.flags.PLACED_AS_BUILDING end, amount, quiet)
+elseif positionals[1] == "building" then
+    local amount = positionals[2] or 1
+    order_instruments(function(instr) return instr.flags.PLACED_AS_BUILDING end, amount, quiet)
 end
+`