[quickfort] docs and misc updates

changelog.txt

@@ -20,6 +20,7 @@ that repo.
 
 ## Misc Improvements
 - `gui/autodump`: add option to clear the ``trader`` flag from teleported items, allowing you to reclaim items dropped by merchants
+- `quickfort`: now handles zones, locations, stockpile configuration, hauling routes, and more
 - `suspendmanager`: now suspends construction jobs on top of floor designations, protecting the designations from being erased
 
 ## Removed

docs/gui/quickfort.rst

@@ -2,14 +2,16 @@ gui/quickfort
 =============
 
 .. dfhack-tool::
-    :summary: Apply pre-designed blueprints to your fort.
+    :summary: Apply layout blueprints to your fort.
     :tags: fort design productivity buildings map stockpiles
 
 This is the graphical interface for the `quickfort` script. Once you load a
 blueprint, you will see a highlight over the tiles that will be modified. You
 can use the mouse cursor to reposition the blueprint and the hotkeys to
 rotate and repeat the blueprint up or down z-levels. Once you are satisfied,
-click the mouse or hit :kbd:`Enter` to apply the blueprint to the map.
+click the mouse or hit :kbd:`Enter` to apply the blueprint to the map. You can
+apply the blueprint as many times as you wish to different spots on the map.
+Right click or hit :kbd:`Esc` to stop.
 
 Usage
 -----
@@ -26,7 +28,7 @@ dialog is shown where you can select a blueprint to load.
 
 You can also type search terms in the dialog and the list of matching blueprints
 will be filtered as you type. You can search for directory names, file names,
-blueprint labels, modes, or comments. Note that, depending on the active list
+blueprint labels, modes, or comments. Note that, depending on the active
 filters, the id numbers in the list may not be contiguous.
 
 To rotate or flip the blueprint around, enable transformations with :kbd:`t` and

docs/quickfort.rst

@@ -2,7 +2,7 @@ quickfort
 =========
 
 .. dfhack-tool::
-    :summary: Apply pre-designed blueprints to your fort.
+    :summary: Apply layout blueprints to your fort.
     :tags: fort design productivity buildings map stockpiles
 
 Quickfort reads stored blueprint files and applies them to the game map.
@@ -24,13 +24,6 @@ There are many ready-to-use blueprints in the
 so you can use this tool productively even if you haven't created any blueprints
 yourself.
 
-.. admonition:: Note
-
-    quickfort is still in the process of being updated for the new version of
-    DF. Stockpiles (the "place" mode), zones (the "zone" mode), building
-    configuration (the "query" mode), and game configuration (the "config" mode)
-    are not yet supported.
-
 Usage
 -----
 
@@ -74,10 +67,9 @@ Usage
 :orders:  Uses the manager interface to queue up workorders to manufacture items
           needed by the specified blueprint(s).
 :undo:    Applies the inverse of the specified blueprint. Dig tiles are
-          undesignated, buildings are canceled or removed (depending on their
-          construction status), and stockpiles/zones are removed. There is no
-          effect for query and config blueprints since they can contain
-          arbitrary key sequences that are not reversible.
+          undesignated, buildings are canceled or scheduled for destruction
+          (depending on their construction status), and stockpiles/zones are
+          removed.
 
 Examples
 --------
@@ -93,7 +85,7 @@ Examples
     List all the blueprints that have both "dreamfort" and "help" as keywords.
 ``quickfort run library/dreamfort.csv``
     Run the first blueprint in the ``library/dreamfort.csv`` file (which happens
-    to be the blueprint that displays the help).
+    to be the "notes" blueprint that displays the help).
 ``quickfort run library/pump_stack.csv -n /dig --repeat up,80 --transform ccw,flipv``
     Dig a pump stack through 160 z-levels up from the current cursor location
     (each repetition of the ``library/pump_stack.csv -n /dig`` blueprint is 2
@@ -117,15 +109,15 @@ Command options
 ``<options>`` can be zero or more of:
 
 ``-c``, ``--cursor <x>,<y>,<z>``
-    Use the specified map coordinates instead of the current map cursor for the
-    the blueprint start position. If this option is specified, then an active
-    game map cursor is not necessary.
+    Use the specified map coordinates instead of the current keyboard map
+    cursor for the the blueprint start position. If this option is specified,
+    then an active keyboard map cursor is not necessary.
 ``-d``, ``--dry-run``
     Go through all the motions and print statistics on what would be done, but
     don't actually change any game state.
 ``--preserve-engravings <quality>``
-    Don't designate tiles for digging if they have an engraving with at least
-    the specified quality. Valid values for ``quality`` are: ``None``,
+    Don't designate tiles for digging/carving if they have an engraving with at
+    least the specified quality. Valid values for ``quality`` are: ``None``,
     ``Ordinary``, ``WellCrafted``, ``FinelyCrafted``, ``Superior``,
     ``Exceptional``, and ``Masterful``. Specify ``None`` to ignore engravings
     when designating tiles. Note that if ``Masterful`` tiles are dug out, the
@@ -154,8 +146,8 @@ Transformations
 
 All transformations are anchored at the blueprint start cursor position. This is
 the upper left corner by default, but it can be modified if the blueprint has a
-`start() modeline marker <quickfort-start>`. This just means that the blueprint
-tile that would normally appear under your cursor will still appear under your
+`start() modeline marker <quickfort-start>`. This means that the blueprint tile
+that would normally appear under your cursor will still appear under your
 cursor, regardless of how the blueprint is rotated or flipped.
 
 ``<transformation>`` is one of:
@@ -213,8 +205,8 @@ statistics structure is a map of stat ids to ``{label=string, value=number}``.
 ``data`` (required)
     A sparse map populated such that ``data[z][y][x]`` yields the blueprint text
     that should be applied to the tile at map coordinate ``(x, y, z)``. You can
-    also just pass a string and it will be interpreted as the value of
-    ``data[0][0][0]``.
+    also just pass a string instead of a table and it will be interpreted as
+    the value of ``data[0][0][0]``.
 ``command``
     The quickfort command to execute, e.g. ``run``, ``orders``, etc. Defaults to
     ``run``.
@@ -225,12 +217,12 @@ statistics structure is a map of stat ids to ``{label=string, value=number}``.
     specified, defaults to ``{x=0, y=0, z=0}``, which means that the coordinates
     in the ``data`` map are used without shifting.
 ``aliases``
-    A map of query blueprint aliases names to their expansions. If not
-    specified, defaults to ``{}``.
+    A map of blueprint alias names to their expansions. If not specified,
+    defaults to ``{}``.
 ``preserve_engravings``
-    Don't designate tiles for digging if they have an engraving with at least
-    the specified quality. Value is a ``df.item_quality`` enum name or value, or
-    the string ``None`` (or, equivalently, ``-1``) to indicate that no
+    Don't designate tiles for digging or carving if they have an engraving with
+    at least the specified quality. Value is a ``df.item_quality`` enum name or
+    value, or the string ``None`` (or, equivalently, ``-1``) to indicate that no
     engravings should be preserved. Defaults to ``df.item_quality.Masterful``.
 ``dry_run``
     Just calculate statistics, such as how many tiles are outside the boundaries
@@ -240,12 +232,11 @@ statistics structure is a map of stat ids to ``{label=string, value=number}``.
 
 API usage example::
 
-    local guidm = require('gui.dwarfmode')
     local quickfort = reqscript('quickfort')
 
-    -- dig a 10x10 block at the cursor position
+    -- dig a 10x10 block at the mouse cursor position
     quickfort.apply_blueprint{mode='dig', data='d(10x10)',
-                              pos=guidm.getCursorPos()}
+                              pos=dfhack.gui.getMousePos()}
 
     -- dig a 10x10 block starting at coordinate x=30, y=40, z=50
     quickfort.apply_blueprint{mode='dig', data={[50]={[40]={[30]='d(10x10)'}}}}

gui/quickfort.lua

@@ -1,14 +1,16 @@
 -- A GUI front-end for quickfort
 --@ module = true
 
+-- reload changed transitive dependencies
+reqscript('quickfort').refresh_scripts()
+
 local quickfort_command = reqscript('internal/quickfort/command')
 local quickfort_list = reqscript('internal/quickfort/list')
 local quickfort_map = reqscript('internal/quickfort/map')
 local quickfort_parse = reqscript('internal/quickfort/parse')
 local quickfort_preview = reqscript('internal/quickfort/preview')
 local quickfort_transform = reqscript('internal/quickfort/transform')
 
-local argparse = require('argparse')
 local dialogs = require('gui.dialogs')
 local gui = require('gui')
 local guidm = require('gui.dwarfmode')
@@ -35,7 +37,7 @@ transformations = transformations or {}
 
 -- displays blueprint details, such as the full modeline and comment, that
 -- otherwise might be truncated for length in the blueprint selection list
-local BlueprintDetails = defclass(BlueprintDetails, dialogs.MessageBox)
+BlueprintDetails = defclass(BlueprintDetails, dialogs.MessageBox)
 BlueprintDetails.ATTRS{
     focus_path='quickfort/dialog/details',
     frame_title='Details',
@@ -62,7 +64,7 @@ end
 
 -- blueprint selection dialog, shown when the script starts or when a user wants
 -- to load a new blueprint into the ui
-local BlueprintDialog = defclass(BlueprintDialog, dialogs.ListBox)
+BlueprintDialog = defclass(BlueprintDialog, dialogs.ListBox)
 BlueprintDialog.ATTRS{
     focus_path='quickfort/dialog',
     frame_title='Load quickfort blueprint',
@@ -616,11 +618,12 @@ end
 
 function Quickfort:do_command(command, dry_run, post_fn)
     self.dirty = true
-    print(('executing via gui/quickfort: quickfort %s'):format(
+    print(('executing via gui/quickfort: quickfort %s --cursor=%d,%d,%d'):format(
                 quickfort_parse.format_command(
-                    command, self.blueprint_name, self.section_name, dry_run)))
+                    command, self.blueprint_name, self.section_name, dry_run),
+                self.saved_cursor.x, self.saved_cursor.y, self.saved_cursor.z))
     local ctx = self:run_quickfort_command(command, dry_run, false)
-    quickfort_command.finish_command(ctx, self.section_name)
+    quickfort_command.finish_commands(ctx)
     if command == 'run' then
         if #ctx.messages > 0 then
             self._dialog = dialogs.showMessage(

quickfort.lua

@@ -3,31 +3,38 @@
 
 local argparse = require('argparse')
 
--- reqscript all internal files here, even if they're not directly used by this
--- top-level file. this ensures modified transitive dependencies are properly
--- reloaded when this script is run.
-local quickfort_aliases = reqscript('internal/quickfort/aliases')
 local quickfort_api = reqscript('internal/quickfort/api')
-local quickfort_build = reqscript('internal/quickfort/build')
-local quickfort_building = reqscript('internal/quickfort/building')
 local quickfort_command = reqscript('internal/quickfort/command')
 local quickfort_common = reqscript('internal/quickfort/common')
-local quickfort_config = reqscript('internal/quickfort/config')
-local quickfort_dig = reqscript('internal/quickfort/dig')
-local quickfort_keycodes = reqscript('internal/quickfort/keycodes')
 local quickfort_list = reqscript('internal/quickfort/list')
-local quickfort_map = reqscript('internal/quickfort/map')
-local quickfort_meta = reqscript('internal/quickfort/meta')
-local quickfort_notes = reqscript('internal/quickfort/notes')
-local quickfort_orders = reqscript('internal/quickfort/orders')
-local quickfort_parse = reqscript('internal/quickfort/parse')
-local quickfort_place = reqscript('internal/quickfort/place')
-local quickfort_preview = reqscript('internal/quickfort/preview')
-local quickfort_query = reqscript('internal/quickfort/query')
-local quickfort_reader = reqscript('internal/quickfort/reader')
 local quickfort_set = reqscript('internal/quickfort/set')
-local quickfort_transform = reqscript('internal/quickfort/transform')
-local quickfort_zone = reqscript('internal/quickfort/zone')
+
+function refresh_scripts()
+    -- reqscript all internal files here, even if they're not directly used by this
+    -- top-level file. this ensures modified transitive dependencies are properly
+    -- reloaded when this script is run.
+    reqscript('internal/quickfort/aliases')
+    reqscript('internal/quickfort/api')
+    reqscript('internal/quickfort/build')
+    reqscript('internal/quickfort/building')
+    reqscript('internal/quickfort/command')
+    reqscript('internal/quickfort/common')
+    reqscript('internal/quickfort/dig')
+    reqscript('internal/quickfort/keycodes')
+    reqscript('internal/quickfort/list')
+    reqscript('internal/quickfort/map')
+    reqscript('internal/quickfort/meta')
+    reqscript('internal/quickfort/notes')
+    reqscript('internal/quickfort/orders')
+    reqscript('internal/quickfort/parse')
+    reqscript('internal/quickfort/place')
+    reqscript('internal/quickfort/preview')
+    reqscript('internal/quickfort/reader')
+    reqscript('internal/quickfort/set')
+    reqscript('internal/quickfort/transform')
+    reqscript('internal/quickfort/zone')
+end
+refresh_scripts()
 
 -- public API
 function apply_blueprint(params)