devel/query

Query is a useful script for finding and reading values of data structure fields. Players can use it to explore data structures or list elements of enums that they might need for another command. Developers can even integrate this script into another script to print data out for a player.

This script takes your data selection (e.g. a data table, unit, item, tile, etc.) and recursively iterates through it, outputting names and values of what it finds.

As it iterates, you can have it do other things, like search for fields that match a Lua pattern or set the value of specific fields.

Warning

This script searches recursive data structures. You can, fairly easily, cause an infinite loop. You can even more easily run a query that simply requires an inordinate amount of time to complete. Set your limits wisely!

Tip

Should the need arise, you can stop devel/query from another shell with kill-lua, e.g. by running dfhack-run kill-lua from another terminal.

Usage

devel/query <source option> <query options> [<additional options>]

Examples

devel/query --unit --getfield id

Prints the id of the selected unit.

devel/query --unit --search STRENGTH --maxdepth 3

Prints out information about the selected unit’s STRENGTH attribute.

devel/query --unit --search physical_attrs --maxdepth 3

Prints out information about all of the selected unit’s physical attributes.

devel/query --tile --search designation

Prints out information about the selected tile’s designation structure.

devel/query --tile --search "occup.*carv"

Prints out information about the carving configuration for the selected tile.

devel/query --table df --maxdepth 0

List the top-level fields in the df data structure.

devel/query --table df.profession --findvalue FISH

Lists the enum values in the df.profession table that contain the substring FISH.

Source options

--table <identifier>

Selects the specified table. You must use dot notation to denote sub-tables, e.g. df.global.world.

--block

Selects the highlighted tile’s block.

--building

Selects the highlighted building.

--item

Selects the highlighted item.

--job

Selects the highlighted job.

--plant

Selects the highlighted plant.

--tile

Selects the highlighted tile’s block, and then uses the tile’s local position to index the 2D data.

--unit

Selects the highlighted unit.

--script <script>

Selects the specified script (which must support being included with reqscript()).

--json <file>

Loads the specified json file as a table to query. The path starts at the DF root directory, e.g. hack/scripts/dwarf_profiles.json.

Query options

--getfield <field>

Gets the specified field from the source.

--search <pattern> [<pattern>]

Searches the source for field names with substrings matching any of the specified patterns.

--findvalue <value>

Searches the source for field values matching the specified value.

--maxdepth <value>

Limits the field recursion depth (default: 7).

--maxlength <value>

Limits the number of items that the script will iterate through in a list (default: 2048).

--excludetypes [a|bfnstu0]

Excludes native Lua data types. Single letters correspond to (in order): (a)ll types listed here, (b)oolean, (f)unction, (n)umber, (s)tring, (t)able, (u)serdata, nil values.

--excludekinds [a|bces]

Excludes DF data types. Single letters correspond to (in order): (a)ll types listed here, (b)itfields, (c)lasses, (e)nums, (s)tructs.

--dumb

Disables intelligent checking for recursive data structures (loops) and increases the --maxdepth to 25 if a value is not already present.

General options

--showpaths

Displays the full path of a field instead of indenting.

--setvalue <value>

Attempts to set the values of any printed fields. Supported types: boolean, string, integer.

--oneline

Reduces output to one line (except with --debugdata) in cases where multiple lines of information is displayed for a field.

--alignto <value>

Specifies the alignment column.

--nopointers

Disables printing values which contain memory addresses.

--debug <value>

Enables debug log verbosity for entries equal to or less than the value provided (valid values: 0-3).

--debugdata

Prints type information under each field.