add optional coordinate validation to coords

library/lua/argparse.lua

@@ -178,8 +178,10 @@ end
 
 -- Parses a comma-separated coordinate string and returns a coordinate table of
 -- {x=x, y=y, z=z}. If the string 'here' is passed, returns the coordinates of
--- the active game cursor, or throws an error if the cursor is not active.
-function coords(arg, arg_name)
+-- the active game cursor, or throws an error if the cursor is not active. This
+-- function also verifies that the coordinates are valid for the current map and
+-- throws if they are not (unless <skip_validation> is set to true).
+function coords(arg, arg_name, skip_validation)
     if arg == 'here' then
         local cursor = guidm.getCursorPos()
         if not cursor then
@@ -187,12 +189,19 @@ function coords(arg, arg_name)
                       '"here" was specified for coordinates, but the game' ..
                       ' cursor is not active!')
         end
+        if not skip_validation and not dfhack.maps.isValidTilePos(cursor) then
+            arg_error(arg_name, 'cursor coordinates not on current map!')
+        end
         return cursor
     end
     local numbers = numberList(arg, arg_name, 3)
-    return xyz2pos(check_nonnegative_int(numbers[1]),
+    local pos = xyz2pos(check_nonnegative_int(numbers[1]),
                         check_nonnegative_int(numbers[2]),
                         check_nonnegative_int(numbers[3]))
+    if not skip_validation and not dfhack.maps.isValidTilePos(pos) then
+        arg_error('specified coordinates not on current map: "%s"', arg)
+    end
+    return pos
 end
 
 return _ENV

test/library/argparse.lua

@@ -153,7 +153,10 @@ function test.numberList()
 end
 
 function test.coords()
-    expect.table_eq({x=0, y=4, z=3}, argparse.coords('0,4 , 3'), 'happy path')
+    mock.patch(dfhack.maps, "isValidTilePos", mock.func(true),
+        function()
+            expect.table_eq({x=0, y=4, z=3}, argparse.coords('0,4 , 3'),
+                            'happy path')
 
             expect.error_match('expected non%-negative integer',
                             function() argparse.coords('1,-2,3') end,
@@ -169,4 +172,24 @@ function test.coords()
                                     function() argparse.coords('here') end,
                                     'inactive cursor')
                 end)
+        end)
+
+    mock.patch(dfhack.maps, "isValidTilePos", mock.func(false),
+        function()
+            expect.error_match('not on current map',
+                               function() argparse.coords('0,4,300') end)
+            expect.table_eq({x=0, y=4, z=300},
+                            argparse.coords('0,4,300', nil, true))
+
+            mock.patch(guidm, 'getCursorPos', mock.func({x=1, y=2, z=300}),
+                function()
+                    expect.error_match('not on current map',
+                                    function() argparse.coords('here') end)
+                end)
+            mock.patch(guidm, 'getCursorPos', mock.func({x=1, y=2, z=300}),
+                function()
+                    expect.table_eq({x=1, y=2, z=300},
+                                    argparse.coords('here', nil, true))
+                end)
+        end)
 end