edit: final draft, with some fixes, is available here:
https://dfhack--1724.org.readthedocs.build/en/1724/docs/guides/quickfort-alias-guide.htmlAlright, I've been writing a "Quickfort Alias Guide" which goes over
#query blueprint alias features, syntax, and usage. I'm also adding a complete walkthrough for the DFHack standard alias library. I'm grateful that A_Curious_Cat brought up the lack of documentation. I'm realizing that there is actually quite a bit to say that I hadn't written down anywhere before.
This is what I have so far. DFHack documentation is written in ReStructuredText (RST) format, but it'll be rendered in nice HTML once it's on docs.dfhack.org. I'm still writing the first draft of the alias library walkthrough. I'll post that too once I have something readable.
.. _quickfort-alias-guide:
Quickfort Alias Guide
=====================
Aliases allow you to use simple words to represent complicated key sequences
when configuring buildings and stockpiles in quickfort ``#query`` blueprints.
For example, say you have the following ``#build`` and ``#place`` blueprints:
::
#build masonry workshop
~, ~,~,`,`,`
~,wm,~,`,`,`
~, ~,~,`,`,`
#place stockpile for mason
~,~,~,s,s,s
~,~,~,s,s,s
~,~,~,s,s,s
and you want to configure the stockpile to hold only non-economic ("other")
stone and to give to the adjacent mason workshop. You could write the
key sequences directly:
::
#query configure stockpile with expanded key sequences
~,~,~,s{Down 5}deb{Right}{Down 2}p^,`,`
~,~,~,g{Left 2}&, `,`
~,~,~,`, `,`
or you could use aliases:
::
#query configure stockpile with aliases
~,~,~,otherstone,`,`
~,~,~,give2left, `,`
~,~,~,`, `,`
If the stockpile had only a single tile, you could also replay both aliases in
a single cell:
::
#query configure mason with multiple aliases in one cell
~,~,~,{otherstone}{give2left},`,`
~,~,~,`, `,`
~,~,~,`, `,`
With aliases, blueprints are much easier to read and understand. They also
save you from having to copy the same long key sequences everywhere.
Alias definition files
----------------------
DFHack comes with a library of aliases for you to use that are always
available when you run a ``#query`` blueprint. Many blueprints can be built
with just those aliases. This "standard alias library" is stored in
:source:`data/quickfort/aliases-common.txt`. The aliases in that file are
described at the `bottom of this document <quickfort-alias-library>`.
Please do not edit the aliases in the standard library directly. The file will
get overwritten when DFHack is updated and you'll lose your changes. Instead,
add your custom aliases to :source:`dfhack-config/quickfort/aliases.txt`.
Definitions in this file take precedence over any definitions in the standard
library.
Alias syntax and usage
----------------------
The syntax for defining aliases is:
::
aliasname: expansion
Where ``aliasname`` is at least two letters or digits long (dashes and
underscores are also allowed) and ``expansion`` is whatever you would type
into the DF UI.
You use an alias by typing its name into a ``#query`` blueprint cell where you
want it to be applied. You can use an alias by itself or as part of a larger
sequence, potentially with other aliases. If the alias is the only text in the
cell, the alias name is matched and its expansion is used. If the alias has
other keys before or after it, the alias name must be surrounded in curly
brackets (:kbd:`{` and :kbd:`}`). An alias can be surrounded in curly brackets
even if it is the only text in the cell, it just isn't necesary. For example,
the following blueprint uses the ``aliasname`` alias by itself in the first
two rows and uses it as part of a longer sequence in the third row:
::
#query apply alias 'aliasname' in three different ways
aliasname
{aliasname}
literaltext{aliasname}literaltext
For a more concrete example of an alias definition, a simple alias that
configures a stockpile to have no bins (:kbd:`C`) and no barrels (:kbd:`E`)
assigned to it would look like this:
::
nocontainers: CE
The alias definition can also contain references to other aliases by including
the alias names in curly brackets. For example, ``nocontainers`` could be
equivalently defined like this:
::
nobins: C
nobarrels: E
nocontainers: {nobins}{nobarrels}
Aliases used in alias definitions *must* be surrounded by curly brackets, even
if they are the only text in the definition:
::
alias1: text1
alias2: alias1
alias3: {alias1}
Here, ``alias1`` and ``alias3`` expand to ``text1``, but ``alias2`` expands to
the literal text ``alias1``.
Keycodes
~~~~~~~~
Non-printable characters, like the arrow keys, are represented by their
keycode name and are also surrounded by curly brackets, like ``{Right}`` or
``{Enter}``. Keycodes are used exactly like aliases -- they just have special
expansions that you wouldn't be able to write yourself. In order to avoid
naming conflicts between aliases and keycodes, the convention is to start
aliases with a lowercase letter.
Any keycode name from the DF interface definition file
(data/init/interface.txt) is valid, but only a few keycodes are actually useful for blueprints:
::
Up
Down
Left
Right
Enter
ESC
Backspace
Page Down
Page Up
Tab
Repetitions
~~~~~~~~~~~
Anything enclosed within curly brackets can also have a number, indicating how
many times that alias or keycode should be repeated. For example:
``{togglesequence 9}`` or ``{Down 5}`` will repeat the ``togglesequence``
alias nine times and the ``Down`` keycode five times, respectively.
Modifier keys
~~~~~~~~~~~~~
Ctrl, Alt, and Shift modifiers can be specified for the next key by adding
them into the key sequence. For example, Alt-h is written as ``{Alt}h``.
Note that DF does not handle keys that have more than a single modifier, so
sequences like ``{Ctrl}{Alt}a`` will result in an error.
Shorthand characters
~~~~~~~~~~~~~~~~~~~~
Some frequently-used keycodes are assigned shorthand characters. Think of them
as single-character aliases that don't need to be surrounded in curly
brackets:
::
& expands to {Enter}
@ expands to {Shift}{Enter}
~ expands to {Alt}
! expands to {Ctrl}
^ expands to {ESC}
If you need literal versions of the shorthand characters, surround them in
curly brackets, for example: use ``{!}`` for a literal exclamation point.
Built-in aliases
~~~~~~~~~~~~~~~~
Most aliases that come with DFHack are in ``aliases-common.txt``, but there is
one alias built into the code for the common shorthand for "make room":
::
r+ expands to r+{Enter}
This needs special code support since ``+`` can't normally be used in alias
names. You can use it just like any other alias, either by itself in a cell
(``r+``) or surrounded in curly brackets (``{r+}``).
Sub-aliases
~~~~~~~~~~~
You can specify sub-aliases that will only be defined while the current alias
is being resolved. This is useful for "injecting" custom behavior into the
middle of a larger alias. For example:
::
{quantumstopfromeast name="Trash Dump"}
The value of the sub-alias ``name`` is used in the middle of the definition of
``quantumstopfromeast`` to give a useful name to your quantum dump hauling
route. Without sub-aliases, we'd have to write something like:
::
{quantumstopfromeastprefix}Trash Dump{quantumstopfromeastsuffix}
which is more difficult to write and more difficult to understand.
A handy technique is to define an alias with some sort of default
behavior and then use sub-aliases to override that behavior as necessary. For
example, here is a simplified version of the standard ``quantum`` alias that
sets up quantum stockpiles:
::
quantum_enable: {enableanimals}{enablefood}{enablefurniture}...
quantum: {linksonly}{nocontainers}{quantum_enable}
You can use the default behavior of ``quantum_enable`` by just using the
``quantum`` alias by itself. But you can override ``quantum_enable`` to just
enable furniture for some specific stockpile like this:
::
{quantum quantum_enable={enablefurniture}}
Sub-aliases must be in one of the following formats:
::
subaliasname=keyswithnospaces
subaliasname="keys with spaces or {aliases}"
subaliasname={singlealias}
If you specify both a sub-alias and a number of repetitions, the number for
repetitions goes last, right before the :kbd:`}`:
::
{alias subaliasname=value repetitions}
Beyond query mode
~~~~~~~~~~~~~~~~~
``#query`` blueprints normally do things in DF :kbd:`q`\uery mode, but nobody
said that we have to *stay* in query mode. ``#query`` blueprints send
arbitrary key sequences to Dwarf Fortress. Anything you can do by typing keys
into DF, you can do in a ``#query`` blueprint. It is absolutely fine to
temporarily exit out of query mode, go into, say, hauling or zone or hotkey
mode, and do whatever needs to be done.
You just have to make certain to exit out of that alternate mode and get back
into :kbd:`q`\uery mode at the end of the key sequence. That way quickfort can
continue on configuring the next tile -- a tile configuration that assumes the
game is still in query mode.
For example, here is the standard library alias for giving a name to a zone:
::
namezone: ^i{givename}^q
The first :kbd:`\^` exits out of query mode. Then :kbd:`i` enters zones mode.
We then reuse the standard alias for giving something a name. Finally, we exit
out of zones mode with another :kbd:`\^` and return to :kbd:`q`\uery mode.
.. _quickfort-alias-library:
The DFHack standard alias library
---------------------------------
TODO
Author
Topic: DFHack: quickfort | buildingplan | blueprint | blueprints/library (Read 92281 times)