Contents
DF structures described by the xml files in library/xml are exported to lua code as a tree of objects and functions under the df global, which broadly maps to the df namespace in C++.
WARNING: The wrapper provides almost raw access to the memory of the game, so mistakes in manipulating objects are as likely to crash the game as equivalent plain C++ code would be. E.g. NULL pointer access is safely detected, but dangling pointers aren't.
Objects managed by the wrapper can be broadly classified into the following groups:
Typed object pointers (references).
References represent objects in DF memory with a known type.
In addition to fields and methods defined by the wrapped type, every reference has some built-in properties and methods.
Untyped pointers
Represented as lightuserdata.
In assignment to a pointer NULL can be represented either as nil, or a NULL lightuserdata; reading a NULL pointer field returns nil.
Named types
Objects in the df tree that represent identity of struct, class, enum and bitfield types. They host nested named types, static methods, builtin properties & methods, and, for enums and bitfields, the bi-directional mapping between key names and values.
The global object
df.global corresponds to the df::global namespace, and behaves as a mix between a named type and a reference, containing both nested types and fields corresponding to global symbols.
In addition to the global object and top-level types the df global also contains a few global builtin utility functions.
The underlying primitive lua object is userdata with a metatable. Every structured field access produces a new userdata instance.
All typed objects have the following built-in features:
ref1 == ref2, tostring(ref)
References implement equality by type & pointer value, and string conversion.
pairs(ref)
Returns an iterator for the sequence of actual C++ field names and values. Fields are enumerated in memory order. Methods and lua wrapper properties are not included in the iteration.
ref._kind
Returns one of: primitive, struct, container, or bitfield, as appropriate for the referenced object.
ref._type
Returns the named type object or a string that represents the referenced object type.
ref:sizeof()
Returns size, address
ref:new()
Allocates a new instance of the same type, and copies data from the current object.
ref:delete()
Destroys the object with the C++ delete operator. If destructor is not available, returns false.
WARNING: the lua reference object remains as a dangling pointer, like a raw C++ pointer would.
ref:assign(object)
Assigns data from object to ref. Object must either be another ref of a compatible type, or a lua table; in the latter case special recursive assignment rules are applied.
ref:_displace(index[,step])
Returns a new reference with the pointer adjusted by index*step. Step defaults to the natural object size.
References of the _kind 'primitive' are used for objects that don't fit any of the other reference types. Such references can only appear as a value of a pointer field, or as a result of calling the _field() method.
They behave as structs with one field value of the right type.
Struct references are used for class and struct objects.
They implement the following features:
ref.field, ref.field = value
Valid fields of the structure may be accessed by subscript.
In case of inheritance, superclass fields have precedence over the subclass, but fields shadowed in this way can still be accessed as ref['subclasstype.field'].
This shadowing order is necessary because vtable-based classes are automatically exposed in their exact type, and the reverse rule would make access to superclass fields unreliable.
ref._field(field)
Returns a reference to a valid field. That is, unlike regular subscript, it returns a pointer reference even for primitive typed fields.
ref:vmethod(args...)
Named virtual methods are also exposed, subject to the same shadowing rules.
pairs(ref)
Enumerates all real fields (but not methods) in memory (= declaration) order.
Containers represent vectors and arrays, possibly resizable.
A container field can associate an enum to the container reference, which allows accessing elements using string keys instead of numerical indices.
Implemented features:
ref._enum
If the container has an associated enum, returns the matching named type object.
#ref
Returns the length of the container.
ref[index]
Accesses the container element, using either a 0-based numerical index, or, if an enum is associated, a valid enum key string.
Accessing an invalid index is an error, but some container types may return a default value, or auto-resize instead for convenience. Currently this relaxed mode is implemented by df-flagarray aka BitArray.
ref._field(index)
Like with structs, returns a pointer to the array element, if possible. Flag and bit arrays cannot return such pointer, so it fails with an error.
pairs(ref), ipairs(ref)
If the container has no associated enum, both behave identically, iterating over numerical indices in order. Otherwise, ipairs still uses numbers, while pairs tries to substitute enum keys whenever possible.
ref:resize(new_size)
Resizes the container if supported, or fails with an error.
ref:insert(index,item)
Inserts a new item at the specified index. To add at the end, use #ref as index.
ref:erase(index)
Removes the element at the given valid index.
Bitfields behave like special fixed-size containers. The _enum property points to the bitfield type.
Numerical indices correspond to the shift value, and if a subfield occupies multiple bits, the ipairs order would have a gap.
Named types are exposed in the df tree with names identical to the C++ version, except for the :: vs . difference.
All types and the global object have the following features:
type._kind
Evaluates to one of struct-type, class-type, enum-type, bitfield-type or global.
type._identity
Contains a lightuserdata pointing to the underlying DFHack::type_instance object.
Types excluding the global object also support:
type:sizeof()
Returns the size of an object of the type.
type:new()
Creates a new instance of an object of the type.
type:is_instance(object)
Returns true if object is same or subclass type, or a reference to an object of same or subclass type. It is permissible to pass nil, NULL or non-wrapper value as object; in this case the method returns nil.
In addition to this, enum and bitfield types contain a bi-directional mapping between key strings and values, and also map _first_item and _last_item to the min and max values.
Struct and class types with instance-vector attribute in the xml have a type.find(key) function that wraps the find method provided in C++.
The df table itself contains the following functions and values:
NULL, df.NULL
Contains the NULL lightuserdata.
df.isnull(obj)
Evaluates to true if obj is nil or NULL; false otherwise.
df.isvalid(obj[,allow_null])
For supported objects returns one of type, voidptr, ref.
If allow_null is true, and obj is nil or NULL, returns null.
Otherwise returns nil.
df.sizeof(obj)
For types and refs identical to obj:sizeof(). For lightuserdata returns nil, address
df.new(obj), df.delete(obj), df.assign(obj, obj2)
Equivalent to using the matching methods of obj.
df._displace(obj,index[,step])
For refs equivalent to the method, but also works with lightuserdata (step is mandatory then).
df.is_instance(type,obj)
Equivalent to the method, but also allows a reference as proxy for its type.