Update exterminate script and documentation

docs/exterminate.rst

@@ -36,6 +36,9 @@ Examples
     Kill all non-friendly creatures.
 ``exterminate all:MALE``
     Kill all non-friendly male creatures.
+``exterminate -f -c bird_turkey -m knockout`
+    Target all turkey children on the map, including friendly ones, and put them
+    into an unconscious state.
 
 Options
 -------
@@ -49,6 +52,10 @@ Options
     Specifies the tool should also kill units friendly to the player.
 ``-l``, ``--limit <num>``
     Set the maximum number of units to exterminate.
+``-c``, ``--children-only``
+    Target only child units. Useful for timer-based automation scripts
+    that periodically remove wandering poults or other child creatures
+    that may endanger dwarven children.
 
 Methods
 -------

exterminate.lua

@@ -1,6 +1,8 @@
 --@module = true
 
 local argparse = require('argparse')
+-- for profession constants
+local profession = df.profession
 
 local function spawnLiquid(position, liquid_level, liquid_type, update_liquids)
   local map_block = dfhack.maps.getTileBlock(position)
@@ -28,9 +30,14 @@ local function checkUnit(opts, unit)
     if not opts.include_friendly and not dfhack.units.isDanger(unit) and not dfhack.units.isWildlife(unit) then
         return false
     end
+    -- filter by caste if specified
     if opts.selected_caste and opts.selected_caste ~= df.creature_raw.find(unit.race).caste[unit.caste].caste_id then
         return false
     end
+    -- filter only children if requested
+    if opts.children_only and unit.profession ~= profession.CHILD then
+        return false
+    end
     return true
 end
 
@@ -167,13 +174,15 @@ local options, args = {
     only_visible = false,
     include_friendly = false,
     limit = -1,
+    children_only = false,
 }, {...}
 
 local positionals = argparse.processArgsGetopt(args, {
     {'h', 'help', handler = function() options.help = true end},
     {'m', 'method', handler = function(arg) options.method = killMethod[arg:upper()] end, hasArg = true},
     {'o', 'only-visible', handler = function() options.only_visible = true end},
     {'f', 'include-friendly', handler = function() options.include_friendly = true end},
+    {'c', 'children-only', handler = function() options.children_only = true end},
     {'l', 'limit', handler = function(arg) options.limit = argparse.positiveInt(arg, 'limit') end, hasArg = true},
 })