### Install XML Dump Executable

Source: https://github.com/dfhack/df-structures/blob/master/tools/CMakeLists.txt

Installs the 'xml-dump-type-sizes' executable to the destination directory if the INSTALL_XMLDUMP option is enabled.

```cmake
if(INSTALL_XMLDUMP)
        install(TARGETS xml-dump-type-sizes DESTINATION .)
    endif()
```

--------------------------------

### Complex Field Access Example

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

This example demonstrates a complex access path involving multiple dereferences and array indexing, showing how implicit steps are handled at runtime.

```text
$global.world.units.all[0].id
```

--------------------------------

### Enable XML Dump Utilities Installation

Source: https://github.com/dfhack/df-structures/blob/master/tools/CMakeLists.txt

Enables the installation of utilities that dump DF-structures information. This option is OFF by default and is often used in conjunction with BUILD_XMLDUMP.

```cmake
option(INSTALL_XMLDUMP "Install utilities that dump df-structures information (for CI)" OFF)
```

--------------------------------

### Fetch and Configure fmt Library

Source: https://github.com/dfhack/df-structures/blob/master/tools/CMakeLists.txt

Fetches the fmt library from a Git repository and makes it available for use. This is part of the setup for building XML dump utilities.

```cmake
INCLUDE(FetchContent)
    FetchContent_Declare(
        fmt
        GIT_REPOSITORY https://github.com/fmtlib/fmt.git
        GIT_TAG 790b9389ae99c4ddebdd2736a8602eca1fec684e # 12.1.0 + bugfix for MSVC warning + build time improvements
    )
    FetchContent_MakeAvailable(fmt)
    set(FMTLIB fmt)
    add_definitions("-DUSE_FMTLIB")
```

--------------------------------

### Container with Pointer and Ref Target

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Example of a container with 'pointer-type' and 'ref-target' attributes, showing the eventual rewrite to include nested pointer and type tags.

```xml
<container pointer-type='int32_t' ref-target='foo'/>
```

```xml
<container pointer-type='int32_t' ref-target='foo'>
        <pointer type-name='int32_t' ref-target='foo'>
            <int32_t ref-target='foo'/>
        </pointer>
    </container>
```

--------------------------------

### Accessing Global Vector Elements with Index

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

This example shows how to access an element from a global vector using the element's index, which is provided as '$'. This is useful for dynamically populating GUI information.

```XML
<compound name='burrows'>
        <stl-vector name='list' pointer-type='burrow'/>
        <int32_t name='sel_index' refers-to='$$._parent.list[$]'/>
    </compound>
```

--------------------------------

### Sequence Item Count and Existence

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Use '$ref.count' to get the number of items in a sequence. '$ref.has-items' checks if the sequence contains any items, returning T or NIL.

```text
$ref.count
```

```text
$ref.has-items
```

--------------------------------

### STL Vector Definition with Index Reference

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

An example of defining an 'stl-vector' with an 'index-refers-to' attribute, used for tracking counts of created weapons.

```xml
<stl-vector name='created_weapons' type-name='int32_t' index-refers-to='$global.world.raws.itemdefs.weapons[$]'/>
```

--------------------------------

### Complex Cross-References Between Arrays

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

This example demonstrates intricate cross-references between vectors using 'refers-to' and 'index-refers-to'. It shows how to access elements in one vector based on the index or value of elements in another related vector.

```XML
<stl-vector name='body_parts' pointer-type='body_part_raw'/>
```

```XML
<stl-vector name='modifiers' pointer-type='bp_appearance_modifier'/>
```

```XML
<stl-vector name='modifier_idx' type-name='int32_t'
                        refers-to='$$._parent._parent.modifiers[$]'
                        index-refers-to='$$._parent.part_idx[$].refers-to.layers[$]'/>
```

```XML
<stl-vector name='part_idx' type-name='int16_t'
                        refers-to='$$._global.body_info.body_parts[$]'/>
```

```XML
<stl-vector name='layer_idx' type-name='int16_t'
                        refers-to='$$._parent._parent.part_idx[$$._key].refers-to.layers[$]'
                        index-refers-to='$$._parent.part_idx[$].refers-to'/>
```

--------------------------------

### XML Data Definition Example

Source: https://context7.com/dfhack/df-structures/llms.txt

Defines an enumeration, a structure, and a global object within the root data-definition element. Free text comments are ignored by the code generator.

```xml
<!-- df.example.xml -->
<data-definition>
    <!-- Free text comments are allowed and ignored by codegen -->

    <enum-type type-name='my_enum' base-type='int32_t'>
        <enum-item name='None' value='-1'/>
        <enum-item name='Alpha'/>
        <enum-item name='Beta'/>
    </enum-type>

    <struct-type type-name='my_struct'>
        <int32_t name='id'/>
        <enum type-name='my_enum' name='kind'/>
    </struct-type>

    <global-object name='my_global' type-name='my_struct'/>
</data-definition>
```

--------------------------------

### Accessing Compound Fields

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Use '@ref.field' or '@ref._fields.field' to get a reference to a specific field within a compound object. '@ref.*' retrieves references to all fields.

```text
@ref.field
```

```text
@ref._fields.field
```

```text
@ref.*
```

--------------------------------

### Enum Definition with Attributes

Source: https://context7.com/dfhack/df-structures/llms.txt

Defines an enumeration with per-item string and boolean attributes. The base-type is int32_t and items auto-increment unless a value is specified. Access examples for generated C++ and Lua are provided.

```xml
<!-- Enum with per-item string and boolean attributes -->
<enum-type type-name='profession' base-type='int32_t'>
    <enum-attr name='caption'/>                          <!-- const char* attribute, default NULL -->
    <enum-attr name='military' type-name='bool' default-value='false'/>

    <enum-item name='MASON'>
        <item-attr name='caption' value='Mason'/>
    </enum-item>
    <enum-item name='WARRIOR'>
        <item-attr name='caption' value='Warrior'/>
        <item-attr name='military' value='true'/>
    </enum-item>
    <enum-item name='DRUNK'>
        <item-attr name='caption' value='Drunk'/>
    </enum-item>
</enum-type>

<!-- Access in generated C++ / Lua:
     df::profession::MASON               // enum value
     df::enum_traits<df::profession>::attrs[df::profession::MASON].caption  // "Mason"
     df::enum_traits<df::profession>::attrs[df::profession::WARRIOR].military // true
-->
```

--------------------------------

### Generate C++ Headers with codegen.pl

Source: https://context7.com/dfhack/df-structures/llms.txt

Use this script to read XML definitions, apply transformations, and generate C++ header files and static initialization fragments. Ensure XML files are in the current directory and specify an output directory.

```bash
# Basic invocation — reads df.*.xml from current dir, writes to ./codegen/
perl codegen.pl . ./codegen df
```

--------------------------------

### Code Helper for GUI Descriptions

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

The '<code-helper name='describe'>' tag specifies code to generate additional informational items for the GUI table. The code should return a string or a list of strings.

```lisp
<code-helper name='describe'> (describe-obj $.name) </code-helper>
```

--------------------------------

### Embed Lisp Expressions for GUI and Instance Lookup with <code-helper>

Source: https://context7.com/dfhack/df-structures/llms.txt

Attach named Lisp code fragments to type or field nodes for custom GUI descriptions ('describe') or lookup paths ('find-instance') for cross-references.

```xml
<struct-type type-name='art_image_chunk'
             instance-vector='$global.world.art_image_chunks'
             key-field='id'>
    <int32_t name='id'/>
    <stl-vector pointer-type='art_image' name='images'/>

    <!-- Custom describe: show the chunk id in the GUI info column -->
    <code-helper name='describe'> (format nil "chunk ~a" $.id) </code-helper>
</struct-type>

<struct-type type-name='art_image' key-field='id'>
    <int32_t name='id'/>
    <int32_t name='chunk_id' ref-target='art_image_chunk'/>

    <!-- find-instance: look up art_image via its chunk + local index -->
    <code-helper name='find-instance'>
        $(find-instance $art_image_chunk $$).images[$]
    </code-helper>
</struct-type>
```

--------------------------------

### Declare Runtime-Initialized Global Pointers with <global-object>

Source: https://context7.com/dfhack/df-structures/llms.txt

Declare global pointers that are initialized at DFHack startup from symbols.xml. The syntax mirrors the <pointer> tag but without 'is-array'. Access these from C++ plugins via the df::global namespace.

```xml
<!-- In df.d_basics.xml -->
<global-object name='world' type-name='world'/>
<global-object name='ui'    type-name='ui'/>
<global-object name='enabler' type-name='enabler'/>
```

```cpp
// Access from DFHack C++ plugin:
     df::world *w = df::global::world;
     if (!w) { out.printerr("world not available\n"); return CR_FAILURE; }
     size_t unit_count = w->units.all.size();
```

--------------------------------

### Accessing All Elements of an Array

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Demonstrates how to use '@' with a wildcard to retrieve all elements of an array.

```lisp
(@ foo '*)
```

--------------------------------

### Using _global for Global Type References

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Demonstrates the use of '$$._global' as a shorthand to reference globally defined types. It simplifies navigation by allowing direct access to global instances from any nested structure.

```XML
<stl-vector name='part_idx' type-name='int16_t'
                        refers-to='$$._global.body_info.body_parts[$]'/>
```

--------------------------------

### Code Helper for Instance Finding

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Use '<code-helper name='find-instance'>' to explicitly define how to find an instance by ID when attributes are insufficient. It receives the field value as '$' and aux-value as '$$'.

```lisp
<code-helper name='find-instance'>$(find-instance $art_image_chunk $$).images[$]</code-helper>
```

--------------------------------

### Create XML Dump Executable

Source: https://github.com/dfhack/df-structures/blob/master/tools/CMakeLists.txt

Defines an executable target named 'xml-dump-type-sizes' using the generated C++ source file. It also sets up include directories and links against the fmt library.

```cmake
add_executable(xml-dump-type-sizes dump-type-sizes.cpp)
    add_dependencies(xml-dump-type-sizes generate_headers)
    target_include_directories(xml-dump-type-sizes PRIVATE ${dfapi_SOURCE_DIR}/include)
    target_link_libraries(xml-dump-type-sizes PRIVATE ${FMTLIB})
```

--------------------------------

### Create Cross-Reference Hyperlinks with 'refers-to' and 'ref-target'

Source: https://context7.com/dfhack/df-structures/llms.txt

Use 'refers-to' for arbitrary Lisp expressions returning a target object, or 'ref-target' as shorthand for finding an instance by field value. 'aux-value' can supply a secondary key.

```xml
<struct-type type-name='unit'>
    <!-- refers-to: direct expression — links to the nemesis record by value -->
    <int32_t name='nemesis_id' refers-to='$global.world.nemesis.all[$]'/>

    <!-- ref-target shorthand — find creature_raw by integer id -->
    <int32_t name='race'  ref-target='creature_raw'/>

    <!-- aux-value: pass race as the secondary key when finding the caste -->
    <int16_t name='caste' ref-target='caste_raw' aux-value='$$.race'/>

    <!-- _parent navigation: sel_index links into the burrow list held by the parent compound -->
    <compound name='burrows'>
        <stl-vector name='list' pointer-type='burrow'/>
        <int32_t name='sel_index' refers-to='$$._parent.list[$]'/>
    </compound>
</struct-type>
```

--------------------------------

### Enable XML Dump Utilities Build

Source: https://github.com/dfhack/df-structures/blob/master/tools/CMakeLists.txt

Enables the build of utilities that dump DF-structures information, typically for CI purposes. This option is OFF by default.

```cmake
option(BUILD_XMLDUMP "Build utilities that dump df-structures information (for CI)" OFF)
```

--------------------------------

### Define Platform-Specific Address Table with <symbol-table>

Source: https://context7.com/dfhack/df-structures/llms.txt

Matches DF executables using MD5 hashes or PE timestamps to provide absolute addresses for global objects and vtable entries. Specify the OS type and hash value.

```xml
<symbol-table name='linux64-df-53.11' os-type='linux'>
    <md5-hash value='a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4'/>

    <!-- Absolute address of the 'world' global pointer -->
    <global-address name='world'  value='0x5f3a20c0'/>
    <global-address name='ui'     value='0x5f3a2100'/>
    <global-address name='cursor' value='0x5f3b0000'/>

    <!-- Pre-seeded vtable address for df::unit (offset within libgraphics.so) -->
    <vtable-address name='unit' value='0x1234560' base='libgraphics.so'/>
</symbol-table>
```

--------------------------------

### Memory Object Reference Properties

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Illustrates accessing various properties of a memory-object-ref, including its value, indexed elements, subfields, parent, and global references.

```lisp
@ref.value
@ref[integer]
@ref.*
@ref.@
@ref._parent
@ref._global
@ref._upglobal
```

--------------------------------

### Accessing Global Objects

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Retrieve a list of references to all known global objects using '@global.*'. Using '$global.*' returns values for primitive globals, which is less common.

```text
@global.*
```

--------------------------------

### Define Ordinary Virtual Method

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines an ordinary virtual method with an optional name and return type. Fields within the tag are treated as parameters.

```xml
<vmethod name='id' ret-type='type'>
        [<ret-type .../>]
        <field1.../>
        <field2.../>
        ...
    </vmethod>
```

--------------------------------

### Memory Object Reference Data Access

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Demonstrates accessing the underlying data of a memory-object-ref, such as its address, size, key, and type name.

```lisp
$ref._address
$ref._size
$ref._key
$ref._type
```

--------------------------------

### Define C-style Struct with Instance Vector

Source: https://context7.com/dfhack/df-structures/llms.txt

Use `<struct-type>` to declare C-style structs. The `instance-vector` and `key-field` attributes enable automatic generation of a `find()` method for binary searching instances.

```xml
<struct-type type-name='historical_figure'
             instance-vector='$global.world.history.figures'
             key-field='id'>
    <int32_t name='id'/>
    <stl-string name='name'/>
    <int32_t name='race'   ref-target='creature_raw'/>
    <int16_t name='caste'  ref-target='caste_raw' aux-value='$$.race'/>

    <compound name='relationships'>
        <stl-vector pointer-type='histfig_relationship' name='list'/>
    </compound>

    <bitfield type-name='histfig_flags' name='flags'/>
</struct-type>
```

```cpp
df::historical_figure* hf = df::historical_figure::find(42); // binary search by id
     hf->name;       // std::string
     hf->race;       // int32_t, hyperlinked to creature_raw
```

--------------------------------

### Define Static String Field

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a fixed-size character array string.

```xml
<static-string name='id' size='bytes'/>
```

--------------------------------

### Generate Type Sizes C++ Source File

Source: https://github.com/dfhack/df-structures/blob/master/tools/CMakeLists.txt

Defines a custom command to generate the 'dump-type-sizes.cpp' source file using a Python script. This command depends on XML files and the Python generator script.

```cmake
file(GLOB XML_FILES ../df.*.xml)
    set(TYPE_DUMP_GENERATOR "${CMAKE_CURRENT_SOURCE_DIR}/generate-type-dump.py")
    add_custom_command(OUTPUT dump-type-sizes.cpp
        COMMAND ${Python_EXECUTABLE} "${TYPE_DUMP_GENERATOR}"
            --template "${CMAKE_CURRENT_SOURCE_DIR}/dump-type-sizes.cpp.in"
            --output "${CMAKE_CURRENT_BINARY_DIR}/dump-type-sizes.cpp"
            --perl "${PERL_EXECUTABLE}"
        VERBATIM
        DEPENDS ${XML_FILES} "${TYPE_DUMP_GENERATOR}"
    )
```

--------------------------------

### Defining ref-target for Simple References

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Shows how 'ref-target' is used to specify a simple reference to a global type, like 'creature_raw'. The reference evaluates a helper function, passing the field's value as '$'.

```XML
<int32_t name='race' ref-target='creature_raw'/>
```

--------------------------------

### Dereferencing Pointer Targets

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Shows various ways to retrieve the target object of a pointer reference, including using '$ref[t]', '@ref[t]', '$ref._target', and '@ref._target'.

```lisp
$ref[t]
@ref[t]
$ref._target
@ref._target
```

--------------------------------

### Define Global Object

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Declares a global pointer initialized from symbols.xml. It is identical to <pointer> but does not allow is-array.

```xml
<global-object name='id' type-name='...'/>
```

```xml
<global-object name='id'>
        <field.../>
    </global-object>
```

--------------------------------

### Lisp Code Parsing with Parentheses

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

When '$' or '@' is immediately followed by parentheses, their contents are parsed as ordinary lisp code.

```lisp
($ (func arg arg...)) '$bar)
```

--------------------------------

### Sequence Index Target Reference

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

If a sequence has the 'index-refers-to' attribute, this syntax retrieves the target for a given index.

```text
@ref.index-refers-to[int]
```

--------------------------------

### CMake Integration for DFHack Plugins

Source: https://context7.com/dfhack/df-structures/llms.txt

Integrate DF-Structures into your DFHack plugin build using CMake. Add the df-structures repository as a submodule and link against the provided CMake interface target.

```cmake
# Integration via CMake (DFHack's build system):
#   add_subdirectory(df-structures)    # in parent CMakeLists.txt
#   target_link_libraries(my_plugin dfhack::structures)
```

--------------------------------

### Accessing Sequence Elements

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Access sequence elements by integer index using '@ref[int]'. Symbolic access is possible if an 'index-enum' is defined. '@ref.*' returns all items, and '@ref._items' returns them as a lazy object.

```text
@ref[int]
```

```text
@ref[symbol]
```

```text
@ref.*
```

```text
@ref._items
```

--------------------------------

### Pointer Dereferencing Transformations

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Illustrates how pointer dereferencing operations are transformed by first accessing the target object's value.

```lisp
($ ref key) -> ($ (@ ref t) key)
(@ ref key) -> (@ (@ ref t) key)
```

--------------------------------

### Define STL Filesystem Path Field

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a field representing a filesystem path using std::filesystem::path.

```xml
<stl-fs-path name='id'/>
```

--------------------------------

### Accessing a Field Across Array Elements

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Shows how to use '$' with a wildcard to access a specific field across all elements of an array.

```lisp
$array.*.field
```

--------------------------------

### Using aux-value with ref-target for Complex References

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Illustrates how 'aux-value' can provide additional context to 'ref-target' by supplying a value for the '$$' argument in the helper function. This is useful when the target reference depends on a parent field.

```XML
<int16_t name='caste' ref-target='caste_raw' aux-value='$$.race'/>
```

--------------------------------

### Define Static Array

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a simple C++ array of a specified length. Use when the size is fixed.

```xml
<static-array name='id' count='123' />
```

--------------------------------

### Container Rewrite Rule: Default Padding

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Automatic rewrite rule where a container with no specified item defaults to assuming padding.

```xml
<container>
            <padding size='4'/>
        </container>
```

--------------------------------

### Abstract Container Syntax

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Represents a generic container that requires exactly one nested field to specify the contained item. This is a placeholder for actual container tags.

```xml
<container>
        <field .../>
    </container>
```

--------------------------------

### Implicit Element Tag for Vector References

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Explains that 'refers-to' on a vector is applied to an implicitly constructed element tag. This clarifies how '$' and '$$' are interpreted within the context of vector elements.

```XML
<stl-vector name='part_idx'>
        <int16_t refers-to='$$._global.body_info.body_parts[$]'/>
    </stl-vector>
```

--------------------------------

### Generic Functions for Dereferencing

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines the generic functions '@' for l-value and '$' for r-value dereferencing, along with its setf method.

```lisp
(defgeneric @ (obj key))
(defgeneric $ (obj key))
(defgeneric (setf $) (obj key))
```

--------------------------------

### Define Symbol Table

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines symbol tables in symbols.xml, specifying locations of global objects and virtual tables.

```xml
<symbol-table name='...' os-type='...'>
        <md5-hash value='...'/>
        <binary-timestamp value='0x...'/>
        ...

        <global-address name='...' [value='0x...']/>
        ...

        <vtable-address name='...' [value='0x...'] [base='...']/>
        ...
    </symbol-table>
```

--------------------------------

### Define DF Static Flag Array

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a StaticBitArray<numbytes,enum> field. Specify the number of bytes and the index enum.

```xml
<df-static-flagarray name='id' index-enum='enum' count='numbytes'/>
```

--------------------------------

### Define Container Field Tags in DFHack Structures

Source: https://context7.com/dfhack/df-structures/llms.txt

Use these tags to declare different types of container fields within a struct-type. Supports STL vectors, static arrays, bit vectors, DFHack flag arrays, linked lists, and pointers to arrays.

```xml
<struct-type type-name='world_data'>
    <!-- std::vector<unit*> with symbolic index via enum -->
    <stl-vector name='all_units' pointer-type='unit'
                index-enum='units_vector_index'/>

    <!-- Fixed C array -->
    <static-array name='region_tiles' type-name='world_region_details*'
                  count='16'/>

    <!-- std::vector<bool> (BitVector) — note: separate tag from stl-vector -->
    <stl-bit-vector name='feature_flags'/>

    <!-- DFHack BitArray keyed by an enum -->
    <df-flagarray name='entity_flags' index-enum='entity_flag'/>

    <!-- DF-style linked list -->
    <df-linked-list name='job_list' type-name='job_link'/>

    <!-- Pointer to an array of int32_t -->
    <pointer name='counts' type-name='int32_t' is-array='true'/>

    <!-- index-refers-to: each element links to the corresponding itemdef -->
    <stl-vector name='created_weapons' type-name='int32_t'
                index-refers-to='$global.world.raws.itemdefs.weapons[$]'/>
</struct-type>
```

--------------------------------

### Sequence Container Attributes

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Attributes for sequence containers that specify GUI hyperlinks based on item index or associate an enum with container indices.

```xml
``index-refers-to='expr'``
```

```xml
``index-enum='enum_type'``
```

--------------------------------

### Define Polymorphic Class with Virtual Methods

Source: https://context7.com/dfhack/df-structures/llms.txt

Use `<class-type>` for polymorphic types supporting virtual methods. The `<virtual-methods>` block defines method signatures, including destructors and custom methods. Anonymous `<vmethod>` tags act as placeholders for unknown slots.

```xml
<class-type type-name='abstract_building'
            original-name='abstract_buildingst'>
    <int32_t name='id'/>
    <enum type-name='abstract_building_type' name='type'/>

    <virtual-methods>
        <vmethod is-destructor='true'/>
        <vmethod name='getType' ret-type='abstract_building_type'/>
        <vmethod name='getName'>
            <ret-type><stl-string/></ret-type>
        </vmethod>
        <!-- Unknown slot — placeholder -->
        <vmethod/>
        <vmethod name='canFunctionAsRoom' ret-type='bool'/>
    </virtual-methods>
</class-type>
```

```cpp
     df::abstract_building *ab = ...;
     df::abstract_building_type t = ab->getType();
     std::string nm = ab->getName();
```

--------------------------------

### Define DF Flag Array

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a BitArray<enum> field. Requires an index-enum attribute.

```xml
<df-flagarray name='id' index-enum='enum'/>
```

--------------------------------

### Define Wide Static String Field

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a fixed-size wide character array string.

```xml
<static-wstring name='id' size='words'/>
```

--------------------------------

### Accessing Nested Structure via Layer Index

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Navigates through parent structures and uses the '_key' attribute to access elements within a 'part_idx' vector, following a 'refers-to' link to its 'layers'.

```dfscript
refers-to='$$._parent._parent.part_idx[$$._key].refers-to.layers[$]'
```

--------------------------------

### Define Primitive Fields for Struct Members

Source: https://context7.com/dfhack/df-structures/llms.txt

Use primitive tags like `<int32_t>`, `<stl-string>`, and `<bool>` to define scalar members within structs. Attributes like `ref-target`, `aux-value`, and `refers-to` enable GUI hyperlinks.

```xml
<struct-type type-name='item_constructed'>
    <!-- Signed / unsigned integers -->
    <int32_t  name='id'/>
    <uint16_t name='wear' init-value='0'/>
    <int16_t  name='mat_type'  ref-target='material' aux-value='$$.mat_index'/>
    <int32_t  name='mat_index' init-value='-1'/>

    <!-- Boolean -->
    <bool name='artifact'/>

    <!-- String types -->
    <stl-string name='description'/>
    <ptr-string  name='raw_name'/>                    <!-- char* -->
    <static-string name='tag' size='32'/>             <!-- char[32] -->

    <!-- Filesystem path (std::filesystem::path) -->
    <stl-fs-path name='texture_path'/>

    <!-- Refers-to: GUI link to the item's owner unit -->
    <int32_t name='owner_id' refers-to='$global.world.units.all[$]'/>
</struct-type>
```

--------------------------------

### Define DF Linked List

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines an ad-hoc DF-style linked list. This is equivalent to a compound type but displayed as a list.

```xml
<df-linked-list name='id' type-name='foo_link'/>
```

--------------------------------

### Lambda Expression Parsing with '@$'

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

An initial '@' followed by one or more '$' characters and then parentheses is parsed as a lambda expression with one argument.

```lisp
(@ $(foo bar baz))
```

--------------------------------

### Define Bitfield

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines an ad-hoc bitfield with flags. An optional base type can be specified.

```xml
<bitfield name='id' [base-type='uint32_t']>
        <flag-bit name='key1'/>
        ...
    </bitfield>
```

--------------------------------

### Accessing Structure Part Index

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Accesses the 'part_idx' of a structure and then an element within that index. Returns an integer value.

```dfscript
tmp = @xxx.part_idx
tmp = @tmp[foo]
($ tmp t)
```

--------------------------------

### Container Rewrite Rule: pointer-type

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Automatic rewrite rule where 'pointer-type' attribute on a container is converted into a nested pointer tag.

```xml
<container pointer-type='foo' .../>
```

```xml
<container ...>
            <pointer type-name='foo' .../>
        </container>
```

--------------------------------

### Define Padding Field

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines an unmarked area of raw bytes with specified size and optional alignment.

```xml
<padding name='id' size='bytes' [alignment='1/2/4'] .../>
```

--------------------------------

### Define Pointer String Field

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a string field represented by a character pointer.

```xml
<ptr-string name='id'/>
```

--------------------------------

### Define STL String Field

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a string field using std::string.

```xml
<stl-string name='id'/>
```

--------------------------------

### Dereferencing Structure Part Index

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Accesses the 'part_idx' of a structure, then an element within that index, and finally follows the 'refers-to' link to evaluate its target object.

```dfscript
tmp = @xxx.part_idx
tmp = @tmp[foo]
obj = @tmp.refers-to
($ obj t)
```

--------------------------------

### Container Rewrite Rule: type-name

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Automatic rewrite rule where 'type-name' attribute on a container is converted into a nested compound or primitive type tag.

```xml
<container type-name='foo' .../>
```

```xml
<container ...>
            <compound type-name='foo' .../>
        </container>
```

```xml
<container ...>
            <foo .../>
        </container>
```

--------------------------------

### Define DF Array

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a DfArray<item> field. Use for DF-specific array types.

```xml
<df-array name='id' />
```

--------------------------------

### Bitfield Definition with Multi-bit Fields

Source: https://context7.com/dfhack/df-structures/llms.txt

Defines a bitfield backed by an unsigned integer. Each flag-bit occupies one bit by default, but the 'count' attribute can widen a bit to a multi-bit sub-field. Usage in generated C++ is shown.

```xml
<bitfield-type type-name='unit_flags1' base-type='uint32_t'>
    <flag-bit name='dead'/>
    <flag-bit name='on_ground'/>
    <flag-bit name='hidden_in_ambush'/>
    <flag-bit name='invisible'/>
    <flag-bit name='rider' count='1'/>
    <!-- Multi-bit field: stores a 4-bit value -->
    <flag-bit name='mood' count='4' type-name='unit_mood_type'/>
</bitfield-type>

<!-- Usage in generated C++:
     unit->flags1.dead        // bool
     unit->flags1.mood        // df::unit_mood_type (4 bits)
     unit->flags1.whole       // raw uint32_t
-->
```

--------------------------------

### Dereferencing Pointers to Primitive Fields

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

When dealing with pointers to primitive fields, explicit dereferencing using '.value' is required, e.g., '$struct.ptrfield.value'.

```text
$struct.ptrfield.value
```

--------------------------------

### Container Rewrite Rule: Multiple Nested Fields

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Automatic rewrite rule where multiple nested fields within a container are aggregated into a single compound tag.

```xml
<container ...>
            <field1 .../>
            <field2 .../>
        </container>
```

```xml
<container ...>
            <compound ...>
                <field1 .../>
                <field2 .../>
            </compound>
        </container>
```

--------------------------------

### Define Integer Field

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a numeric field with a specific integer type.

```xml
<int32_t name='id'வுகளை/>
```

--------------------------------

### Define Boolean Field

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a boolean field.

```xml
<bool name='id'/>
```

--------------------------------

### Define STL Set

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines an std::set<item> field. Use for ordered collections of unique elements.

```xml
<stl-set name='id' />
```

--------------------------------

### Define DF Other Vectors Type

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a tuple of vectors with the same base type, acting as individual vectors keyed by an enum.

```xml
<df-other-vectors-type type-name='foo_other' index-enum='foo_other_id' item-type='foo'/>
```

--------------------------------

### Define Class Type

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a type with virtual methods, similar to struct-type but disallowing unions and requiring a virtual method table.

```xml
<class-type type-name='name' inherits-from='class_type' original-name='vtable_name'>
        ...
        fields
        ...
        <virtual-methods>
            ...
            vmethods
            ...
        </virtual-methods>
    </class-type>
```

--------------------------------

### Define DF Linked List Node Type

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines the structure for a DF-style linked list node, including item, previous, and next pointers.

```xml
<df-linked-list-type type-name='foo_link' item-type='foo'/>
```

--------------------------------

### Define Virtual Destructor

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a virtual destructor within the <virtual-methods> section of a class type.

```xml
<vmethod is-destructor='true'/>
```

--------------------------------

### Define Structure Type

Source: https://github.com/dfhack/df-structures/blob/master/SYNTAX.rst

Defines a structure type with optional attributes like union, inheritance, instance vector, and key field.

```xml
<struct-type type-name='name'
            [is-union='true/false']
            [inherits-from='struct_type']
            [instance-vector='expr']
            [key-field='identifier']>
    ...
    fields
    ...
</struct-type>
```